Device information
Device name |
TriSpectorP |
|---|---|
Firmware version |
4.2.0.214R |
Date |
2020-03-30 |
Crowns
- C
-
Cipher Cipher.AES Cipher.Certificate Cipher.Certificate.SigningRequest Cipher.Key Cipher.RSA Command Command.Client Command.Methods Connector Connector.DigitalIn Connector.DigitalOut Connector.DigitalOut.DelayedEvents Connector.Increment Container
- D
-
DateTime DigitalLogic DigitalLogic.Delay DigitalLogic.EdgeDetector DigitalLogic.Gate DigitalLogic.TFlipFlop
- E
-
Encoder Engine Engine.AsyncFunction Engine.AsyncFunction.Future Engine.Event Engine.EventBinding Engine.FunctionBinding Engine.SyncEvent Engine.WebServer
- F
-
FTPClient FTPServer FieldBus File File.Archive File.Archive.ZIP
- H
- I
-
Image Image.Calibration Image.Calibration.CameraModel Image.Calibration.Correction Image.Fixture Image.Fixture3D Image.Format Image.Format.BMP Image.Format.JPEG Image.Format.PNG Image.Matching Image.Matching.EdgeMatcher Image.Matching.EdgeMatcher3D Image.Matching.PatternMatcher Image.Matching.PatternVerifier Image.Matching.PointMatcher Image.OCR Image.OCR.Halcon Image.OCR.Halcon.AutoSegmenter Image.OCR.Halcon.FontClassifier Image.OCR.Halcon.ManualSegmenter Image.OCR.Halcon.SegmenterResult Image.PixelRegion Image.PixelRegion.Filter Image.Provider Image.Provider.Camera Image.Provider.Camera.V3TConfig2D Image.Provider.Camera.V3TConfig3D Image.Provider.Directory Image.Pyramid Image.ShapeFitter Image.SurfaceFitter
- L
-
LED LUA.debug LUA.math LUA.string LUA.table LUA.utf8 Log Log.Handler Log.Logger Log.SharedLogger
- M
-
MachineLearning MachineLearning.Bayes MachineLearning.DataSet MachineLearning.Fisher MachineLearning.KMeansClustering MachineLearning.KNearestNeighbors MachineLearning.NeuralNet MachineLearning.RandomForest MachineLearning.SupportVectorMachine Matrix Mesh Monitor Monitor.App Monitor.CPU Monitor.Memory Monitor.Network
- N
- O
-
OPCUA OPCUA.Server OPCUA.Server.EndpointConfiguration OPCUA.Server.FileCertificateStoreConfiguration OPCUA.Server.Namespace OPCUA.Server.Node OPCUA.Server.SecurityConfiguration OPCUA.Server.ServerConfiguration OPCUA.Server.UserTokenDatabase OPCUA.Server.Value Object
- P
-
Parameters Parameters.Listener Parameters.Node Parameters.Validator Point PointCloud PointCloud.Matching PointCloud.Matching.Halcon PointCloud.Matching.Halcon.SurfaceMatcher PointCloud.RangeFilter Profile Profile.Curve Profile.CurveFitter Profile.Log Profile.Matching Profile.Matching.PatternMatcher
- S
-
Script Script.Queue SensorData SerialCom Shape Shape.Composite Shape3D Statistics
- T
-
TCPIPClient TCPIPServer TCPIPServer.Connection Text Timer Transform TriSpector
- U
- V
-
View View.Camera View.ColorMap View.GraphDecoration View.ImageDecoration View.MeshDecoration View.PixelRegionDecoration View.PointCloudDecoration View.ShapeDecoration View.TextDecoration
Cipher
Namespace for different kinds of en- and decryption ciphers
Overview
Cipher.AES
AES cipher support
Functions
decrypt()
Decrypts AES-encrypted data (OpenAES compatible)
| Name | Type | Description |
|---|---|---|
encryptedData |
BINARY |
The AES encrypted data to be decrypted |
key |
BINARY |
The decryption key. Has to be 16, 24, or 32 bytes long (= 128, 192 or 256 bits) |
| Name | Type | Description |
|---|---|---|
decryptedData |
BINARY |
The decrypted result. When any encryption stage goes wrong, or an invalid AES key is passed, an empty binary result is returned |
decrypted = Cipher.AES.decrypt(encryptedData, key)
encrypt()
Encrypts data. The mode of operation is CBC. An IV is generated randomly and stored in a OpenAES-compatible header that is part of the ciphertext (return value).
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The data to be encrypted |
key |
BINARY |
The encryption key. Has to be 16, 24, or 32 bytes long (= 128, 192 or 256 bits) |
| Name | Type | Description |
|---|---|---|
encryptedData |
BINARY |
The encrypted result. When any decryption stage goes wrong, or an invalid AES key is passed, an empty binary result is returned |
encrypted = Cipher.AES.encrypt(data, key)
Cipher.Certificate
Functionality to work with X.509 certificates.
Cipher.Certificate.SigningRequest
Allows to generate certificate signing requests according to the PKCS #10 specification.
Overview
Functions
addSubjectField()
Adds a field to the subject of the certificate signing request. The subject of the certificate can consist of multiple fields, each field being a key/value-pair.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
subjectField |
STRING |
The subject field to add |
value |
STRING |
The value for this subject field |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns 'true' if subjectField could be added successfully. |
Cipher.Certificate.SigningRequest.addSubjectField(handle, "CN", "myCommonName")
create()
Creates a new certificate signing request instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the certificate signing request. |
local csr = Cipher.Certificate.SigningRequest.create()
encode()
Encodes the signed certificate signing request into a binary buffer.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
format |
ENUM Format |
Optional passphrase. |
| Name | Type | Description |
|---|---|---|
csr |
BINARY |
Returns binary representation of the certificate signing request, or nil on error. |
local success = Cipher.Certificate.SigningRequest.encode(handle)
setKeyPair()
Sets the public key that will be included in the signing request and the private key that will be used to sign the request.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
publicKey |
OBJECT Cipher.Key |
The public key to include in the certificate signing request. |
privateKey |
OBJECT Cipher.Key |
The private key which is used to sign the certificate signing request. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns 'true' if key pair could be loaded successfully. |
Cipher.Certificate.SigningRequest.setKeyPair(handle, publicKey, privateKey)
Cipher.Key
Represents a key to be used in public-key cryptosystem.
Overview
Functions
encode()
Encodes a key into a binary buffer.
| Name | Type | Description |
|---|---|---|
key |
OBJECT Cipher.Key |
The instance object to use |
format |
ENUM Format |
Optional passphrase. |
passphrase |
STRING |
Optional passphrase. Ignored if this is not a private key. |
| Name | Type | Description |
|---|---|---|
buffer |
BINARY |
Returns binary representation of the key, or nil on error. |
local keyBuf = Cipher.Key.encode(key, "PEM", "mypassphrase")
Cipher.RSA
RSA public-key cryptosystem support.
Overview
Functions
generateKeyPair()
Generates a RSA key pair and stores the keys in PEM file format.
| Name | Type | Description |
|---|---|---|
size |
INT |
Length of the modulus in bits. Typical sizes are 2048 or 4096. |
| Name | Type | Description |
|---|---|---|
publicKey |
OBJECT Cipher.Key |
The generated public key. Nil in case of error. |
privateKey |
OBJECT Cipher.Key |
The generated private key. Nil in case of error. |
local publicKey, privateKey = Cipher.RSA.generateKeyPair(2048)
Command
Command handling functionalities
Overview
Functions
Command.Client
A client to connect to a command server and execute SOPAS commands. Command servers can be other devices which speak SOPAS CoLaA, CoLaB or CoLa2. A client can execute single commands on the device and also can store and restore parameters of it. To be able to talk with a device, a ".sopas" file is needed to be specified with the "Command.Client.setDescription" function. A ".sopas" file can be created using SOPAS ET and store a project. The connection to the device must be injected using the "setConnection" function by providing a handle to a connection which is already open and configured. Connections must be CROWNs which have a "transmit" function and an "OnReceive" event, e.g. "TCPIPClient" and "SerialCom". The handling of disconnects can be handled by the user. There is a default timeout for every request of 30 seconds. If the connection is lost or no response is received, the requests return with an error after that time. There is a fix internal maximum CoLa de/serialization buffer size of 64k. Request bigger than this are not possible.
Overview
backup(), close(), create(), createNode(), deregister(), disableChangeListener(), enableChangeListener(), getDevicesFromDescriptionFile(), getVariantsForDeviceFromDescriptionFile(), invoke(), open(), read(), register(), restore(), setAccessMode(), setByteOrder(), setConnection(), setDescriptionFile(), setDeviceSelector(), setProtocol(), setRequestTimeout(), write()
Functions
backup()
Stores the parameters of a device to a ".sopas" file. This is useful to backup the parameters of a device to a file to restore it later or to open it in SOPAS ET. If storing fails no file is created at all. The opposite function is "restore" to put all parameters to a device.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
paramFile |
STRING |
The path to the .sopas file to store to |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successful stored the parameters to the file. False if not possible or failed while storing. |
errMsg |
STRING |
If backup fails, this string contains the readable error message about why it failed |
local bSuccess = Command.Client.backup(handle, "private/myDevice.sopas")
close()
Forces a close from the server. Can be used to shut down the communication and reconfigure the "Command.Client"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
Command.Client.close(handle)
create()
Creates a new Command.Client instance. The client needs to be configured before using the Open()-function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The new instance |
-- Create and configure the connection
conHandle = TCPIPClient.create()
TCPIPClient.setIPAddress(conHandle, "192.168.0.1")
TCPIPClient.connect(conHandle)
assert( TCPIPClient.isConnected(conHandle) ) -- connection handling has to be done by the user of the Command.Client
-- Create, configure and open the client
handle = Command.Client.create()
Command.Client.setDescriptionFile(handle, "resources/myDevice.sopas")
Command.Client.setProtocol(handle, "COLA_A")
Command.Client.setConnection(handle, conHandle)
assert ( Command.Client.open(handle) )
-- Now the ".sopas"-file is loaded and the client is registered at the connection and can be used
-- read a variable from the device
local paramNode = Command.Client.read(handle, "DeviceIdent")
if paramNode then
local devName = Parameters.Node.get(paramNode, "Name")
print("Device name is " .. devName)
end
createNode()
Creates a new Parameters.Node with a defined structure for a variable or as method argument. This can be used for write or invoke calls.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
paramName |
STRING |
The communication name of the variable or method. |
| Name | Type | Description |
|---|---|---|
paramNode |
OBJECT Parameters.Node |
The new created not if exists |
local newNode = Command.Client.createNode(handle, "theParameterName")
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
disableChangeListener()
Removes the registration for a variable change
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventName |
STRING |
The communication name of the variable. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully disabled. False if was not enabled before, timed out or error |
local bSuccess = Command.Client.disableChangeListener(handle, "theEventName")
enableChangeListener()
Register for variable change of the device. All incoming changes are directly received after this call, therefore use the "register" function to register for the "OnChanged" event before.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventName |
STRING |
The communication name of the variable. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if already registered, timed out or error |
local bSuccess = Command.Client.enableChangeListener(handle, "theEventName")
getDevicesFromDescriptionFile()
Retrieve the names of the devices, that are stored within the description file previously set with setDescriptionFile.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
| Name | Type | Description |
|---|---|---|
deviceNames |
STRING |
A vector containing all the found device names. Empty names are also valid values. Nil is returned, if the description file was not set or is not parseable. An Empty vector is empty, if the description file was loaded successfully but does not contain any devices. |
Command.Client.getDevicesFromDescriptionFile(handle)
getVariantsForDeviceFromDescriptionFile()
Retrieve all possible variants for a device stored in the previously set with setDescriptionFile.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
deviceName |
STRING |
The name of the device to get the variants for. Should be a value which was previously returned by getDevicesFromDescriptionFile. |
| Name | Type | Description |
|---|---|---|
variantNames |
STRING |
A vector containing all the found variant names. For a device without variants, a vector with a single, emtpy variant name is returned. Nil is returned, if the description file was not set or is not parseable. |
Command.Client.getVariantsForDeviceFromDescriptionFile(handle, "DeviceName")
invoke()
Invokes a method on the device and waits until it is finished. If the method has arguments the createNode function can be used to set them and pass to this function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
methodName |
STRING |
The communication name of the method. |
paramNode |
CONST_OBJECT Parameters.Node |
The node value as arguments if the method has arguments |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully executed. False if timeout or error |
paramNode |
OBJECT Parameters.Node |
The method return values if the method has return values |
local methodArg = Command.Client.createNode(handle, "theMethodName")
local bSuccess,methodResults = Command.Client.invoke(handle, "theMethodName", methodArg)
open()
Opens the client with the current configuration and makes usage possible. The configuration values have to be set before calling this function. The open()-function sends no command to device, just loads the configuration and make communication with device possible.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully opened. False if configuration isn’t valid (e.g. wrong description file) |
errMsg |
STRING |
If open fails, this string contains the readable error message about why it failed |
local bSuccess = Command.Client.open(handle)
read()
Reads a parameter of the connected device and returns its value
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
varName |
STRING |
The communication name of the variable |
| Name | Type | Description |
|---|---|---|
paramNode |
OBJECT Parameters.Node |
The copy of the value. Nil if not exists or was not possible to read. |
local paramNode = Command.Client.read(handle, "theParameterName")
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
restore()
Restores the parameters from a ".sopas" file to the device. This is useful to configure the device in a specific state. If restoring fails the device might be in an inconsistent configuration. The variables are only restored which match the current login level. So make sure to login to the device in the wanted userlevel before. Variables which are above the current userlevel are not written. The opposite function is "backup" to get all parameters from a device.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
paramFile |
STRING |
The path to the .sopas file to restore from |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successful restored all parameters. False if not possible or failed while restoring. |
errMsg |
STRING |
If restore fails, this string contains the readable error message about why it failed |
local bSuccess = Command.Client.restore(handle, "resources/myDevice.sopas")
setAccessMode()
Sets the access mode to use for every request. It depends on the devices if requests by name is possible or not. Smaller devices might only support requests by index. Default is 'by name'. The value can also be changed on the fly when the client is open.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
accessMode |
ENUM AccessMode |
The access mode to use to the device. |
Command.Client.setAccessMode(handle, "BY_INDEX")
setByteOrder()
Sets the CoLa byte order to use for binary cola protocols (CoLaB,CoLa2). Defaults is 'Big-endian'.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
byteOrder |
ENUM ByteOrder |
The cola byte order to use to the device. |
Command.Client.setByteOrder(handle, "LITTLE_ENDIAN")
setConnection()
Sets the connection handle to use for talking with the device. The handle can be of any connection CROWN which serves a "transmit" function and an "OnReceive" event. The connection has already to be opened before and can be control by the user. Also make sure that the connection has to be set to no framing which is the default for most connections. The Client does the framing on its own, so check the setFraming function of the connection. If the connection throws too much receive data, there is a queue of 10 packets and everything more than this is thrown away.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
conHandle |
HANDLE |
The connection handle to use to communicate with the device |
setDescriptionFile()
Sets the path to the ".sopas" file to use as description for the device to communicate with. A ".sopas" file can be created using SOPAS ET and store a project. Take care that the file needs to be created for the correct device variant. The setDeviceSelector()-function can be used to select a device if there are multiple devices in the ".sopas"-file.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
filePath |
STRING |
The path to the file to use as description for the device to communicate with |
Command.Client.setDescriptionFile(handle, "resources/myFile.sopas")
setDeviceSelector()
Sets the device selector which should used to define which description to loaded from the ".sopas" description file. Can be left empty (as per default) to load the first description in the file or if there is just one single description in the file. The selector can be a device type name, device variant and/or the location name. Not used selectors could be set to empty string.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
deviceName |
STRING |
The name of the device to load from the description file. Could be empty string. |
deviceVariant |
STRING |
The variant of the device to load from the description file. Could be empty string. |
locationName |
STRING |
The location name of the device to load from the description file. Could be empty string. |
Command.Client.setDeviceSelector(handle, "Lector652 Flex")
setProtocol()
Sets the protocol to use to the device. Default is "CoLa A".
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
protocol |
ENUM ProtocolType |
The protocol to use to the device. |
Command.Client.setProtocol(handle, "COLA_A")
setRequestTimeout()
Sets the timeout in milliseconds for every request like read, write, invokeMethod, enableChangeListener/disableChangeListener and also backup/restore requests. Default is 30 seconds. Maximum is 65 seconds. The value can also be changed on the fly when the client is open. Only for backup/restore requests the timeout needs to be set before callin the open function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
timoutMs |
INT |
The timeout in ms for every request. Max. 65 seconds. |
Command.Client.setRequestTimeout(handle, 5000)
write()
Writes a value to a parameter of the connected device. The value can retrieved by reading first or using the createNode function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
varName |
STRING |
The communication name of the variable |
paramNode |
CONST_OBJECT Parameters.Node |
The node value to write |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully written. False if parameter was not written. |
local bSucces = Command.Client.write(handle, "theParameterName", paramNode)
Events
OnChanged
Event which is notified if any change listener received a change of a variable. If the event has values, they are provided as a "Parameters.Node" object.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventName |
STRING |
The name of the variable or event which has changed |
paramNode |
OBJECT Parameters.Node |
The event value if the event has arguments |
Command.Methods
Provides functionality to implement CoLa command methods of the device.
Functions
add()
Adds a new method implementation. Every method could only be added once in the system. The added function callback is called if the method is executed. The callback gets the method parameters and also a prepared return parameter objects (if defined any) as function parameters. The callback should set the values on the return parameter object and should return it if successfully executed. If the callback does not return the return value object, there is an error thrown on the CoLa command interface with number 0x14 (internal error) The method parameters and return values are each in a "Parameters.Node"-object. See the sample code for how a callback implementation looks like.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of Command.Methods |
commandName |
STRING |
The command method name as served on CoLa interface |
funcCallback |
STRING |
The function name which implements the method. Needs to have a specific signature, read more about in the function documentation. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if added successfully. False if method does not exist or is already added by someone in the system. |
function callback(paramNode, resultNode)
-- get values from "paramNode" using Parameters.Node-functions
-- set values on "resultNode" using Parameters.Node-functions
-- if successful return the resultNode
return resultNode
end
local bSuccess = Command.Methods.add(handle, "MyMethodName", callback)
create()
Creates a new method handling instance. The methods stay implement as long as this instance exists.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The new Command.Methods instance |
handle = Command.Methods.create()
Connector
Contains CROWNs to access connectors at the device
Overview
Connector.DigitalIn
Provides functionality to control a digital input port at the device
Overview
Functions
create()
Creates a digital input port with the given name if exists and not already in use.
| Name | Type | Description |
|---|---|---|
portName |
ENUM DigitalInPorts |
The devices identifier of the digital input port (e.g. DI1) |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle for the port. Nil if not available or already in use. |
handle = Connector.DigitalIn.create("DI1")
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
get()
Returns the current activation state of the specified input port.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the port. |
| Name | Type | Description |
|---|---|---|
isActive |
BOOL |
True if input port is active, false if inactive. |
local isActive = Connector.DigitalIn.get(handle)
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
setDebounceValue()
The debounce value to use for the debounce mode. Meaning of the value is dependent on the DebounceMode which is set. Default is zero which means no debouncing at all.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the port |
newValue |
INT |
The debounce value to use. Is dependent on the DebounceMode which is set. |
Connector.DigitalIn.setDebounceValue(handle, 10)
setLogic()
Sets the pin inversion of the port to ACTIVE_HIGH or ACTIVE_LOW. Default is ACTIVE_HIGH.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the port |
newLogic |
ENUM SignalLogic |
ACTIVE_HIGH or ACTIVE_LOW |
Connector.DigitalIn.setLogic(handle, "ACTIVE_HIGH")
Events
OnChange
This event is triggered whenever the input port changes its state. The new state is provided as parameter. If there is a new registration done on this event, the current state is also thrown. Please note that there might be state changes missed by the implementation in overload situations and the same state might be notified twice.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the port |
newState |
BOOL |
The state of the level signal |
Connector.DigitalIn.register(handle, "OnChange", "MyApp.handleChange")
OnChangeStamped
This event is triggered whenever the input port changes its state. The new state and exact increment and timestamp are provided as parameter. If there is a new registration done on this event, the current state is also thrown. Please note that there might be state changes missed by the implementation in overload situations and the same state might be notified twice.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the port |
newState |
BOOL |
The state of the level signal |
timeOfStateChange |
INT |
The timestamp in microseconds the state of the signal changed |
incrementOfStateChange |
INT |
The increment stamp in ticks the state of the signal changed |
Connector.DigitalIn.register(handle, "OnChangeStamped", "MyApp.handleChangeStamped")
Connector.DigitalOut
Provides functionality to control a digital output port at the device
Overview
Functions
create()
Creates a digital output port with the given name if exists and not already in use.
| Name | Type | Description |
|---|---|---|
portName |
ENUM DigitalOutPorts |
The devices identifier of the digital output port (e.g. DO1) |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle for the port. Nil if not available or already in use. |
handle = Connector.DigitalOut.create("DO1")
set()
Sets the port state to the given value.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the port |
newState |
BOOL |
The new state of the level signal |
Connector.DigitalOut.set(handle, level)
setActivationMode()
The activation mode to set for this port so that the port is automatically reset after a given time. Default is time based.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the port |
value |
ENUM ActivationMode |
The activation mode to use |
Connector.DigitalOut.setActivationMode(handle, "TIME_MS")
setActivationValue()
The activation value to set for this port. Meaning of the value is dependent on the ActivationMode which is set. Default is zero which means not automatically reset.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the port |
value |
INT |
The activation value to use. Is dependent on the ActivationMode which is set. |
Connector.DigitalOut.setActivationValue(handle, 100)
setLogic()
Sets the pin inversion of the port to ACTIVE_HIGH or ACTIVE_LOW. Default is ACTIVE_HIGH.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the port |
value |
ENUM SignalLogic |
ACTIVE_HIGH or ACTIVE_LOW |
Connector.DigitalOut.setLogic(handle, "ACTIVE_HIGH")
Connector.DigitalOut.DelayedEvents
Provides functionality to control the digital outputs with high precision and a defined delay in time or distance. Output events will be added to a queue so that several events can be added before the first event is activated. The events have both a start value (when the event should start) and a duration value (the time or distance to hold the output active).
Functions
add()
Add a delayed event to the queue. The units of the start and duration values are specified when enabling delayed events for an output.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use. |
startValue |
INT |
Output activation start value in configured unit. |
durationValue |
INT |
Output duration value in configured unit. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if the add was successful, otherwise false. |
status |
ENUM StatusCode |
Result code. |
success, status = Connector.DigitalOut.DelayedEvents.add(handle, startValue, durationValue)
clear()
Removes all events in the queue that have not yet been activated.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if the queue was successfully cleared, otherwise false. |
success = Connector.DigitalOut.DelayedEvents.clear(handle)
create()
Creates a DelayedEvents instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance. |
handle = Connector.DigitalOut.DelayedEvents.create()
disable()
Disables delayed events and removes all events that have not yet been activated. After disabling delayed events, the queue can be reconfigured with enable().
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if disable was successful, otherwise false. |
success = Connector.DigitalOut.DelayedEvents.disable(handle)
enable()
Enable delayed events for a digital output. Configure which output to enable for delayed events, which units to use for start and duration, and a maximum duration timeout. If an event reaches the maximum timeout time before the event duration is complete, it will be automatically deactivated and removed from the queue.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use. |
connectorHandle |
HANDLE |
Output pin to use. |
startUnit |
ENUM MeasurementUnit |
The unit for event start values. |
durationUnit |
ENUM MeasurementUnit |
The unit for event duration values. |
maxDurationTimeout |
INT |
Maximum event duration time (in microseconds). |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successful, otherwise false. |
success = Connector.DigitalOut.DelayedEvents.enable(handle, do4, "TIME_US", "INCREMENT_TICK", 1000000)
Connector.Increment
Represents the input/output pins of an INC plug.
Overview
Functions
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
portName |
The devices identifier of the connector (e.g. INC1) |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
handle = Connector.Increment.create("INC1")
Container
An associative container storing all kind of CROWN datatypes (like objects, strings, booleans etc.). Each item in the container is identified using a string name as key. One item in the container can represent both a single value as well as vectors. Adding to the container is done using a general purpose add()-function. For retrieval of items there are more options: There is a general purpose get() function that provides the item, but type checking of the obtained instance must be done by the user. There is a set of typed functions for retrieving items from the container which check that the item to be retrieved also has the expected type. Internally, the implementation uses a hash map for fast value access. The order of adding items is not relevant. Access to the container is thread-safe.
Overview
Functions
add()
Adds an item to the container. The item can be a float, integer, bool, string or any object. Only works with non-const objects, for const-objects use the "addConst"-function. If an item with the same name already exists in the container, the function returns false. The container itself cannot be added as item.
| Name | Type | Description |
|---|---|---|
container |
OBJECT Container |
Container instance. |
name |
STRING |
Name of the item. Must not be empty. |
item |
AUTO |
Item to add to the container. Nil value is not possible. |
itemType |
ENUM ItemTypes |
Can be specified to set explicitly the type name for the item which should be added. An attempt is made to convert the item to this target type. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successfully added. False if item already exists or item type does not match. |
addConst()
Adds a const item to the container. The item can be a float, integer, bool, string or any object. Objects can be non-const or const and are forced to be const inside the container. If an item with the same name already exists in the container, the function returns false. The container itself cannot be added as item.
| Name | Type | Description |
|---|---|---|
container |
OBJECT Container |
Container instance. |
name |
STRING |
Name of the item. Must not be empty. |
item |
CONST_AUTO |
Item to add to the container. Nil value is not possible. |
itemType |
ENUM ItemTypes |
Can be specified to set explicitly the type name for the item which should be added. An attempt is made to convert the item to this target type. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successfully added. False if item already exists or item type does not match. |
clear()
Clears the entire container.
| Name | Type | Description |
|---|---|---|
container |
OBJECT Container |
Container instance. |
create()
Creates a new container.
| Name | Type | Description |
|---|---|---|
container |
OBJECT Container |
The new container. |
exists()
Checks if an item with the provided key string exists in the container.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
name |
STRING |
Name of the item to check. |
| Name | Type | Description |
|---|---|---|
result |
BOOL |
True if the Container contains an item with the provided key name. |
get()
Get any item from the container. No type-checking is done on the item to get, it can be an integer, float, bool, object etc., or a vector of such types. To get a const-object value use the "getConst"-function. It is up to the user to make sure that the returned value is of the correct type before further usage.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
name |
STRING |
Name of the item. |
itemType |
ENUM ItemTypes |
Can be specified to explicitly get the item only if the type matches. If the item type does not match, nil is returned. |
| Name | Type | Description |
|---|---|---|
item |
AUTO |
Returns item if retrieval was successful, otherwise nil. |
getConst()
Get any item from the container as const. No type-checking is done on the item to get, it can be an integer, float, bool, object etc., or a vector of such types. Objects can be non-const or const and are always returned as const object. It is up to the user to make sure that the returned value is of the correct type before further usage.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
name |
STRING |
Name of the item. |
itemType |
ENUM ItemTypes |
Can be specified to explicitly get the item only if the type matches. If the item type does not match, nil is returned. |
| Name | Type | Description |
|---|---|---|
item |
CONST_AUTO |
Returns item if retrieval was successful, otherwise nil. |
getSize()
Returns the number of items in the container.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
| Name | Type | Description |
|---|---|---|
size |
INT |
Number of items in the container. |
getType()
Returns a the enum string type definition of the underlying type of the item.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
name |
STRING |
Name of the item to check. |
| Name | Type | Description |
|---|---|---|
type |
ENUM ItemTypes |
The string describing the type. Will be nil if the key name is not found. |
isEmpty()
Checks if the container is empty.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
| Name | Type | Description |
|---|---|---|
result |
BOOL |
True if the container is empty. |
isSingle()
Checks if the item with the provided key string is a single instance, as opposed to a vector-valued instance.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
name |
STRING |
Name of the item to check. |
| Name | Type | Description |
|---|---|---|
result |
BOOL |
True if the item with the provided key name is a single instance. False if it is a vector valued instance or if the key name does not exist. |
isType()
Checks if the item with the specified key string is of the specified type.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
name |
STRING |
Name of the item to check. |
type |
ENUM ItemTypes |
The type name to compare against. |
| Name | Type | Description |
|---|---|---|
result |
BOOL |
True if the item with the provided key name is of the queried type. False if it the type is wrong. Nil if the key name does not exist. |
isVector()
Checks if the item with the provided key string is a vector-valued instance, as opposed to a single instance.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
name |
STRING |
Name of the item to check. |
| Name | Type | Description |
|---|---|---|
result |
BOOL |
True if the item with the provided key name is a vector-valued instance. False if it is a single instance or if the key name does not exist. |
list()
Gets a list of all key names in the container in alphabetical order.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
| Name | Type | Description |
|---|---|---|
item |
STRING |
A string vector with the names of all items in the container in alphabetical order. |
remove()
Removes an item from the container. If there is no item with the provided key string, nothing is done and false is returned.
| Name | Type | Description |
|---|---|---|
container |
OBJECT Container |
Container instance. |
name |
STRING |
Name of the item to remove. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if item existed and was removed, false if item did not exist. |
toString()
Returns a string representation of the content of the container.
| Name | Type | Description |
|---|---|---|
container |
CONST_OBJECT Container |
Container instance. |
| Name | Type | Description |
|---|---|---|
description |
STRING |
User-friendly description of the container. |
update()
Updates an existing item in the container. The item can be a float, integer, bool, string or any object. Only works with non-const objects, for const-objects use the "updateConst"-function. If an item with the name does not exist in the container, the function returns false. If the existing item has a different type than specified, the function returns false. The container itself cannot be set as item.
| Name | Type | Description |
|---|---|---|
container |
OBJECT Container |
Container instance. |
name |
STRING |
Name of the item. Must not be empty. |
item |
AUTO |
Item to update in the container. Nil value is not possible. |
itemType |
ENUM ItemTypes |
Can be specified to set explicitly the type name for the item which should be updated. An attempt is made to convert the item to this target type. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successfully updated. False if item does not exist or item type does not match. |
updateConst()
Updates an existing const item in the container. The item can be a float, integer, bool, string or any object. Objects can be non-const or const, and are forced to be const inside the container. If an item with the name does not exist in the container, the function returns false. If the existing item has a different type than specified, the function returns false. The container itself cannot be set as item.
| Name | Type | Description |
|---|---|---|
container |
OBJECT Container |
Container instance. |
name |
STRING |
Name of the item. Must not be empty. |
item |
CONST_AUTO |
Item to update in the container. Nil value is not possible. |
itemType |
ENUM ItemTypes |
Can be specified to set explicitly the type name for the item which should be updated. An attempt is made to convert the item to this target type. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successfully updated. False if item does not exist or item type does not match. |
DateTime
Provides functions to get date and time as well as conversion routines.
Overview
calcDayOfWeek(), calcLocalFromUTC(), convertTimestamp(), convertUnixTime(), create(), createFromTimestamp(), createFromUnixTime(), formatTimestamp(), formatUnixTime(), getDate(), getDateTime(), getDateTimeValuesLocal(), getDateTimeValuesUTC(), getTime(), getTimeZone(), getTimestamp(), getTimestampMicroseconds(), getUnixTime(), isTimeSet(), setDateTime(), setTimeZone(), toString()
Functions
calcDayOfWeek()
Calculates the day of the week in the current time zone as integer (Sunday=0, Monday=1, Tuesday=2, …, Saturday=6. The returned value can be used as key to a table mapping the values to strings if desired (see the example). The return value is a number because of different country-local requirements: In some countries, Sunday is the first day of the week, in some others it’s the Monday. Also, the names of the days may differ. The convention Sunday=0, Monday=1 is derived from the standard C library convention of day of week numbers. For invalid Unix time input the function returns nil.
| Name | Type | Description |
|---|---|---|
unixUTCTime |
INT |
The Unix input time |
| Name | Type | Description |
|---|---|---|
dayNr |
INT |
Number of the current day of week or nil in case of invalid input |
local dayStrEnglish = {} -- English day names
dayStrEnglish[0] = "Sun"
dayStrEnglish[1] = "Mon"
dayStrEnglish[2] = "Tue"
dayStrEnglish[3] = "Wed"
dayStrEnglish[4] = "Thu"
dayStrEnglish[5] = "Fri"
dayStrEnglish[6] = "Sat"
dayStrGerman = {} -- German day names
dayStrGerman[0] = "So"
dayStrGerman[1] = "Mo"
dayStrGerman[2] = "Di"
dayStrGerman[3] = "Mi"
dayStrGerman[4] = "Do"
dayStrGerman[5] = "Fr"
dayStrGerman[6] = "Sa"
local currentDayAsNumber = DateTime.calcDayOfWeek(DateTime.getUnixTime())
local currentDayInEnglish = dayStrEnglish[currentDayAsNumber]
local currentDayInGerman = dayStrGerman[currentDayAsNumber]
calcLocalFromUTC()
Converts Unix time to local time and generates a string like the one returned by getDateTime(). This function is deprecated, please use formatUnixTime() instead.
| Name | Type | Description |
|---|---|---|
unixUTCTime |
INT |
The Unix time |
| Name | Type | Description |
|---|---|---|
dateTime |
STRING |
Format: "Jan..Dec dd yyyy hh:mm:ss" or nil for invalid Unix time input |
local dateTime = DateTime.calcLocalFromUTC(DateTime.getUnixTime() + 10) -- Date and Time 10 seconds in the future
convertTimestamp()
Returns the individual parts (day, month, year, hour, minute, second, millisecond) of the time which is calculated from the input timestamp in milliseconds since bootup.
| Name | Type | Description |
|---|---|---|
timestamp |
INT |
The input timestamp |
asUTC |
BOOL |
True to return UTC, false to convert to local time. Defaults to false (local time). |
| Name | Type | Description |
|---|---|---|
day |
INT |
Day |
month |
INT |
Month |
year |
INT |
Year |
hour |
INT |
Hour |
minute |
INT |
Minute |
second |
INT |
Second |
millisecond |
INT |
Millisecond |
local day, month, year, hour, minute, second, millisecond = DateTime.convertTimestamp(DateTime.getTimestamp())
convertUnixTime()
Returns the individual parts (day, month, year, hour, minute, second) of an input Unix time.
| Name | Type | Description |
|---|---|---|
unixTime |
INT |
The Unix time |
asUTC |
BOOL |
True to return UTC, false to convert to local time. Defaults to false (local time). |
| Name | Type | Description |
|---|---|---|
day |
INT |
Day |
month |
INT |
Month |
year |
INT |
Year |
hour |
INT |
Hour |
minute |
INT |
Minute |
second |
INT |
Second |
local day, month, year, hour, minute, second = DateTime.convertUnixTime(DateTime.getUnixTime())
create()
Returns the current date and time as DateTime object. Only has valid time if the device supports it, otherwise time since bootup.
| Name | Type | Description |
|---|---|---|
dateTime |
OBJECT DateTime |
The current date and time as DateTime object |
local now = DateTime.create()
createFromTimestamp()
Returns the DateTime object which corresponds to the input timestamp in milliseconds since bootup.
| Name | Type | Description |
|---|---|---|
timestamp |
INT |
The input timestamp |
| Name | Type | Description |
|---|---|---|
dateTime |
OBJECT DateTime |
DateTime object which corresponds to the input timestamp |
local now = DateTime.createFromTimestamp(DateTime.getTimestamp())
local bootup = DateTime.createFromTimestamp(0)
createFromUnixTime()
Returns the DateTime object which corresponds to the input Unix time (number of seconds since the "epoch" (Jan 1, 1970) in UTC) Milliseconds are set to 0.
| Name | Type | Description |
|---|---|---|
unixTime |
INT |
The Unix time |
| Name | Type | Description |
|---|---|---|
dateTime |
OBJECT DateTime |
DateTime object which corresponds to the input Unix time |
local now = DateTime.createFromUnixTime(DateTime.getUnixTime())
local epoch = DateTime.createFromUnixTime(0)
formatTimestamp()
Generates a string like the one returned by getDateTime() for the time which is calculated from the input timestamp in milliseconds since bootup.
| Name | Type | Description |
|---|---|---|
timestamp |
INT |
The input timestamp |
asUTC |
BOOL |
True to return UTC, false to convert to local time. Defaults to false (local time). |
| Name | Type | Description |
|---|---|---|
dateTime |
STRING |
Format: "Jan..Dec dd yyyy hh:mm:ss.msecs" or nil for invalid Unix time input |
local localTime = DateTime.formatTimestamp(DateTime.getTimestamp())
local bootupTime = DateTime.formatTimestamp(0)
formatUnixTime()
Generates a string like the one returned by getDateTime() for the input Unix time.
| Name | Type | Description |
|---|---|---|
unixTime |
INT |
The Unix time |
asUTC |
BOOL |
True to return UTC, false to convert to local time. Defaults to false (local time). |
| Name | Type | Description |
|---|---|---|
dateTime |
STRING |
Format: "Jan..Dec dd yyyy hh:mm:ss" or nil for invalid Unix time input |
local localTime = DateTime.formatUnixTime(DateTime.getUnixTime(), false)
local epoch = DateTime.formatUnixTime(0, true)
getDate()
Returns the current date in format "Jan..Dec dd yyyy". Only has valid time if the device supports it, otherwise time since bootup.
| Name | Type | Description |
|---|---|---|
date |
STRING |
Format: "Jan..Dec dd yyyy" |
local time = DateTime.getDate()
getDateTime()
Returns the current date plus time in format "Jan..Dec dd yyyy hh:mm:ss.msecs. This is the same like concatenating the strings returned by getDate and getTime with a space delimiter, but a call to getDateTime is atomic and also works when date/time overflows whereas two calls to getDate and getTime are not guaranteed to fit together because some time could pass by between the calls.
| Name | Type | Description |
|---|---|---|
datetime |
STRING |
Format: "Jan..Dec dd yyyy hh:mm:ss.msecs" |
local dateTime = DateTime.getDateTime()
getDateTimeValuesLocal()
Returns the individual parts (day, month, year, hour, minute, second, millisecond) of the system time in local time.
| Name | Type | Description |
|---|---|---|
day |
INT |
Day |
month |
INT |
Month |
year |
INT |
Year |
hour |
INT |
Hour |
minute |
INT |
Minute |
second |
INT |
Second |
millisecond |
INT |
Millisecond |
local day, month, year, hour, minute, second, millisecond = DateTime.getDateTimeValuesLocal()
getDateTimeValuesUTC()
Returns the individual parts (day, month, year, hour, minute, second, millisecond) of the system time in UTC (Coordinated Universal Time).
| Name | Type | Description |
|---|---|---|
day |
INT |
Day |
month |
INT |
Month |
year |
INT |
Year |
hour |
INT |
Hour |
minute |
INT |
Minute |
second |
INT |
Second |
millisecond |
INT |
Millisecond |
local day, month, year, hour, minute, second, millisecond = DateTime.getDateTimeValuesUTC()
getTime()
Returns the current time in format "hh:mm:ss.msecs". Only has valid time if the device supports it, otherwise time since bootup.
| Name | Type | Description |
|---|---|---|
time |
STRING |
Format: "hh:mm:ss.msecs" |
local time = DateTime.getTime()
getTimeZone()
Returns the currently set time zone in IANA tz database format. The function queries the underlying operating system for the current time zone and returns the corresponding string. When the time zone is not available, or could not be translated into the IANA format, or is not implemented on the operating system, an empty string is returned. When using DateTime.setTimeZone(), the returned string of this function may be different to one set before because the IANA format allows various synonyms for time zones. But it is assured that the returned string describes a time zone that is a synonym to the last one passed to setTimeZone() even if it is different. For example, the result may be "Europe/Vienna" even when "Europe/Berlin" was passed to setTimeZone() because both cities are located in the same time zone.
| Name | Type | Description |
|---|---|---|
timeZone |
STRING |
The currently set time zone or an empty string if getting is not possible |
local currentZone = DateTime.getTimeZone()
getTimestamp()
Returns the system timestamp in milliseconds since bootup.
| Name | Type | Description |
|---|---|---|
timestamp |
INT |
Stamp in milliseconds |
local timestamp = DateTime.getTimestamp()
getTimestampMicroseconds()
Returns the system timestamp in microseconds since bootup.
| Name | Type | Description |
|---|---|---|
timestamp |
INT |
Stamp in microseconds |
local timestamp = DateTime.getTimestampMicroseconds()
getUnixTime()
Returns the current time as number of seconds since the "epoch" (Jan 1, 1970) in UTC (Coordinated Universal Time). The returned value can directly be used to perform arithmetic and calculate time values.
| Name | Type | Description |
|---|---|---|
unixtime |
INT |
The Unix time |
local unixTime = DateTime.getUnixTime()
isTimeSet()
Returns whether the system time has been set (by NTP or some other service) since bootup, so the getDate/Time() calls deliver reliable results.
| Name | Type | Description |
|---|---|---|
isSet |
BOOL |
true when the system date has been set minimum once since bootup |
local timeSetSinceBootUp = DateTime.isTimeSet()
setDateTime()
Sets the system time in either UTC (Coordinated Universal Time) or local time. Attention: The system behaviour might be affected if changing the time too often, so use with care. The usage of NTPClient is generally more recommended. Please also take care when setting local time (not UTC) to an interval where daylight saving time changes to non daylight saving time (mostly in autumn). The results when setting to that time interval are undefined, because the time interval repeats a second time during the transition (for example 2:59:58, 2:59:59, 2:00:00, 2:00:01, …, 2:59:58, 2:59:59, 3:00:00) so the time values are ambiguous.
| Name | Type | Description |
|---|---|---|
year |
INT |
Year to set, range: 1970..2037 |
month |
INT |
Month to set, range: 1..12 |
day |
INT |
Day to set, range: 1..31 |
hour |
INT |
Hour to set, range: 0..23 |
minute |
INT |
Minute to set, range: 0..59 |
second |
INT |
Second to set, range: 0..59 |
asUTC |
BOOL |
True to set in UTC, false to set in local time. Defaults to false (local time). |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
If true, the time was set successfully |
DateTime.setDateTime(2016, 1, 15, 14, 30, 10, true)
setTimeZone()
Sets the time zone of the system. The time zone is encoded in the IANA tz database format. A current list can be looked up from http://en.wikipedia.org/wiki/List_of_tz_database_time_zones. Time zones do not change the system clock which always runs in UTC, but they change how dates and times are interpreted in a locally dependent way. The functions getDateTime(), getDate() and getTime() will return different values when the time zone is overwritten. Note that time zones are subject to political changes, so in the future, time zones of some countries may change even if that is rather unlikely. Not each operating system supports each time zone. So, always check the return code of this function. If the call is unsuccessful, you may need another compatible time zone name or you will need to update your device firmware to fit to the new zones. The Windows version of this function uses a mapping provided by unicode.org, browsable under http://www.unicode.org/cldr/charts/latest/supplemental/zone_tzid.html, so the IANA names can be universally used for each underlying operating system.
| Name | Type | Description |
|---|---|---|
timeZoneString |
STRING |
The time zone string in IANA tz database format |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
If true, the time zone was set successfully |
local result = DateTime.setTimeZone("America/New_York")
toString()
Gets a user-friendly string description of a DateTime object (UTC time according to the ISO 8601 time representation).
| Name | Type | Description |
|---|---|---|
dateTime |
CONST_OBJECT DateTime |
The DateTime object. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of a DateTime object. |
str = DateTime.toString(dateTime)
DigitalLogic
Contains DigitalLogic elements to be used in Control Flows.
DigitalLogic.Delay
Delays incoming signals for a given delay.
Overview
Functions
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
handle = DigitalLogic.Delay.create()
delay()
Starts a delay with a millisecond or mm resolution.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
signal |
BOOL |
The state of the level/Dirac signal to delay |
| Name | Type | Description |
|---|---|---|
delayedSignal |
BOOL |
The state of the delayed level/Dirac signal |
delayedSignal=DigitalLogic.Delay.delay(handle, signal)
highAccuracyDelay()
Starts a delay with a microsecond or increment tick resolution.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
signal |
BOOL |
The state of the level signal to delay |
| Name | Type | Description |
|---|---|---|
delayedSignal |
BOOL |
The state of the delayed level signal |
delayedSignal=DigitalLogic.Delay.highAccuracyDelay(handle, signal)
setDelayDistance()
Distance in mm or increment ticks. Resolution depends on the used function (delay or highAccuracyDelay).
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
delayDistance |
INT |
Distance in mm or increment ticks. Resolution depends on the used function (delay or highAccuracyDelay). |
DigitalLogic.Delay.setDelayDistance(handle, 100)
setDelayTime()
Time in milliseconds or microseconds for the delay. Resolution depends on the used delay function delay or highAccuracyDelay.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
delayTime |
INT |
Time in milliseconds or microseconds. Resolution depends on the used function (delay or highAccuracyDelay). |
DigitalLogic.Delay.setDelayTime(handle, 10)
setMaxQueueSize()
Maximum number of queued signals (0: unlimited). Affects only delay, not highAccuracyDelay.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
maxQueueSize |
INT |
Maximum number of queued signals (0: unlimited) |
DigitalLogic.Delay.setMaxQueueSize(handle, 100)
DigitalLogic.EdgeDetector
Detects edges in a level signal and generates Dirac signals for the falling and rising edge.
Functions
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
handle = DigitalLogic.EdgeDetector.create()
detect()
Detects edges in a level based signal and generates Dirac signals.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
level |
BOOL |
The state of the level signal |
| Name | Type | Description |
|---|---|---|
risingEdge |
BOOL |
Creates a Dirac signal if a rising edge is detected in the level signal. |
fallingEdge |
BOOL |
Creates a Dirac signal if a falling edge is detected in the level signal. |
risingEdge, fallingEdge = DigitalLogic.EdgeDetector.detect(handle, level)
DigitalLogic.Gate
Logical gate functions implemented in hardware or software.
Functions
and()
Combine the input signals with a logical AND.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
levelA |
BOOL |
The state of the first signal |
levelB |
BOOL |
The state of the second signal |
levelC |
BOOL |
The state of the third optional signal |
levelD |
BOOL |
The state of the fourth optional signal |
| Name | Type | Description |
|---|---|---|
level |
BOOL |
Resulting output signal of the logical AND, only if state changed. |
level = DigitalLogic.Gate.and(handle, levelA, levelB, levelC, levelD)
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
handle = DigitalLogic.Gate.create()
nand()
Combine the input signals with a logical NAND.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
levelA |
BOOL |
The state of the first signal |
levelB |
BOOL |
The state of the second signal |
levelC |
BOOL |
The state of the third optional signal |
levelD |
BOOL |
The state of the fourth optional signal |
| Name | Type | Description |
|---|---|---|
level |
BOOL |
Resulting output signal of the logical NAND, only if state changed. |
level = DigitalLogic.Gate.nand(handle, levelA, levelB, levelC, levelD)
nor()
Combine the input signals with a logical NOR.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
levelA |
BOOL |
The state of the first signal |
levelB |
BOOL |
The state of the second signal |
levelC |
BOOL |
The state of the third optional signal |
levelD |
BOOL |
The state of the fourth optional signal |
| Name | Type | Description |
|---|---|---|
level |
BOOL |
Resulting output signal of the logical NOR, only if state changed. |
level = DigitalLogic.Gate.nor(handle, levelA, levelB, levelC, levelD)
not()
Invert the input signal with a logical NOT.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
levelA |
BOOL |
The state of the input signal |
| Name | Type | Description |
|---|---|---|
level |
BOOL |
Resulting output signal of the logical NOT, only if state changed. |
level = DigitalLogic.Gate.not(handle, levelA)
or()
Combine the input signals with a logical OR.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
levelA |
BOOL |
The state of the first signal |
levelB |
BOOL |
The state of the second signal |
levelC |
BOOL |
The state of the third optional signal |
levelD |
BOOL |
The state of the fourth optional signal |
| Name | Type | Description |
|---|---|---|
level |
BOOL |
Resulting output signal of the logical OR, only if state changed. |
level = DigitalLogic.Gate.or(handle, levelA, levelB, levelC, levelD)
setAffinity()
Changes the affinity of the control flow block
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
value |
ENUM Affinity |
Affinity of the gate block. |
DigitalLogic.Gate.setAffinity(handle, newAffinity)
xnor()
Combine the input signals with a logical XNOR. If only one of the input signals is high, the output is low. Attention: Also if three of the input signals are high, the output is still high (this is different than the 3-way xnor definition).
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
levelA |
BOOL |
The state of the first signal |
levelB |
BOOL |
The state of the second signal |
levelC |
BOOL |
The state of the third optional signal |
levelD |
BOOL |
The state of the fourth optional signal |
| Name | Type | Description |
|---|---|---|
level |
BOOL |
Resulting output signal of the logical XNOR, only if state changed. |
level = DigitalLogic.Gate.xnor(handle, levelA, levelB, levelC, levelD)
xor()
Combine the input signals with a logical XOR. If only one of the input signals is high, the output is high. Attention: Also if three of the input signals are high, the output is still low (this is different than the 3-way xor definition).
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
levelA |
BOOL |
The state of the first signal |
levelB |
BOOL |
The state of the second signal |
levelC |
BOOL |
The state of the third optional signal |
levelD |
BOOL |
The state of the fourth optional signal |
| Name | Type | Description |
|---|---|---|
level |
BOOL |
Resulting output signal of the logical XOR, only if state changed. |
level = DigitalLogic.Gate.xor(handle, levelA, levelB, levelC, levelD)
DigitalLogic.TFlipFlop
Toggle a level signal from high to low or vice versa on each incoming Dirac signal.
Functions
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
handle = DigitalLogic.TFlipFlop.create()
toggle()
Toggle a level signal from high to low or vice versa on each incoming Dirac signal. The default state is low.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
signal |
BOOL |
The incoming Dirac signal |
| Name | Type | Description |
|---|---|---|
level |
BOOL |
The resulting level signal |
level = DigitalLogic.TFlipFlop.toggle(handle, signal)
Encoder
Overview
Functions
create()
Creates an encoder with the given name if exists and not already in use.
| Name | Type | Description |
|---|---|---|
encSrc |
The devices identifier of the encoder (e.g. ENC1) |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle for the encoder. Nil if not available or already in use. |
handle = Encoder.create("ENC1")
getCurrentIncrement()
Retrieve the current increment count value and corresponding timestamp.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the encoder object. |
| Name | Type | Description |
|---|---|---|
increment |
INT |
Current increment value. |
timestamp |
INT |
Current timestamp in microseconds. |
local incr, timestamp = Encoder.getCurrentIncrement()
getDirection()
Retrieve the current direction (forward/backward).
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the encoder object. |
| Name | Type | Description |
|---|---|---|
direction |
ENUM Direction |
Current direction (forward/backward). |
local direction = Encoder.getDirection()
getTicksPerSecond()
Retrieve the current speed value (increment/sec).
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the encoder object. |
| Name | Type | Description |
|---|---|---|
ticksPerSecond |
INT |
Current ticks per second value. |
local ticksPerSecond = Encoder.getTicksPerSecond()
setCountMode()
Select how increments will be counted
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
mode |
ENUM DecoderCountMode |
The decoder count mode to set |
Encoder.setCountMode(handle, mode)
setSource()
Sets source for the increment decoder input. Could be either an increment connector (external) or an encoder generator (internal) which could be used for fixed speed.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
sourceHandle |
HANDLE |
Handle of the connected input source. |
Encoder.setSource(handle, sourceHandle)
Engine
Provides functionality to control the AppEngine of the device and use the AppEngine framework.
Overview
Functions
getCrownAsXML()
Returns the manifest xml snippet of the specified CROWN as xml string. Sub-CROWNs are NOT included. Output string starts and ends with the "crown" xml tag. The name of the crown is only the sub-crown name and NOT the full qualified crown name. E.g. requested crown name is "NameA.NameB.NameC", output xml crown name is only "NameC".
| Name | Type | Description |
|---|---|---|
crownName |
STRING |
The full CROWN name to return the manifest |
| Name | Type | Description |
|---|---|---|
manifestXml |
STRING |
The manifest xml snippet of the CROWN or nil if CROWN does not exist |
local manifestString = Engine.getCrownAsXML("TheCrownName")
getCrowns()
Returns the list of all crowns which are available in the engine as vector sorted alphabetically. The domain filter like 'ctrl-flow' can be specified, to only return CROWNs which are relevant for the specified domain. The CROWN can also be relevant if there is just one function or event specified as include. Available domain filters: - ctrl-flow - data-flow - script - remote - java
| Name | Type | Description |
|---|---|---|
domainFilter |
STRING |
If specified, only returns the crowns which have an include specified to the domain like 'ctrl-flow' and no exclude is defined to it. See manifest scheme for all available include-domains. |
| Name | Type | Description |
|---|---|---|
crownVector |
STRING |
The sorted vector for all full-qualified crown names |
local crownList = Engine.getCrowns()
getCurrentAppName()
Get the name of the app from which this function is called.
| Name | Type | Description |
|---|---|---|
name |
STRING |
The name of the app or nil if app context is not available. |
local name = Engine.getCurrentAppName()
getCurrentAppVersion()
Get the version of the app from which this function is called.
| Name | Type | Description |
|---|---|---|
version |
STRING |
The version of the app or nil if app context is not available. |
local version = Engine.getCurrentAppVersion()
getEnumValues()
Returns all enum values of an enum defined in the manifest as a vector sorted alphabetically.
| Name | Type | Description |
|---|---|---|
enumName |
STRING |
The full CROWN enum name to return its values |
| Name | Type | Description |
|---|---|---|
enumVals |
STRING |
The sorted vector of enum values or nil if enum does not exist |
local enumValTable = Engine.getEnumValues("Log.Level")
getFirmwareVersion()
Returns the device firmware version of this engine
| Name | Type | Description |
|---|---|---|
firmwareVersion |
STRING |
The device firmware version of this engine |
getPartNumber()
Returns the device part number of this engine
| Name | Type | Description |
|---|---|---|
partNumber |
STRING |
The device part number of this engine |
getSerialNumber()
Returns the device serial number of this engine as string
| Name | Type | Description |
|---|---|---|
serialNumber |
STRING |
The device serial number of this engine as string |
getTypeCode()
Returns the device type code of this engine
| Name | Type | Description |
|---|---|---|
typeCode |
STRING |
The device type code of this engine |
getTypeName()
Returns the device type name of this engine
| Name | Type | Description |
|---|---|---|
typeName |
STRING |
The device type name of this engine |
getVersion()
Returns the AppEngine version of this device
| Name | Type | Description |
|---|---|---|
engineVersion |
STRING |
The AppEngine version of this device |
isEmulator()
This function return true if the current engine is just an emulator engine and not a real device.
| Name | Type | Description |
|---|---|---|
isEmulator |
BOOL |
True if the current device is an emulator |
listApps()
Returns the names of all apps currently in the engine.
| Name | Type | Description |
|---|---|---|
appList |
STRING |
List of app names |
reboot()
Reboots the device over power cycle directly. Function will NOT return on target hardware. On the emulator the function always returns and logs a warning that reboot is not possible on emulator. This function can only be used after the "Engine.OnStarted" event has been notified to prevent endless reboot loops in global scope. Before the event the function call is ignored. During the first 30 seconds after the "Engine.OnStarted" event the reboot action keeps pending so that an endless reboot loop is prevented. Every 5 seconds there is a log that a reboot is pending, so that the app developer has time to connect and stop the apps.
| Name | Type | Description |
|---|---|---|
reason |
STRING |
Optional string describing the reason for reboot |
Engine.reboot("the concrete reboot reason")
reloadApps()
Reloads all applications of the AppEngine. Function will not return on target hardware and directly reloads. On the emulator the function may return. This function can be used to reset all applications and start them again like if rebooting but without full powercycle. This function can only be used after the "Engine.OnStarted" event has been notified to prevent endless reload loops in global scope.
Engine.reloadApps()
Events
OnStarted
Startup event of the application which is notified once after startup after all apps have been fully loaded. This should be used by apps which are dependent on other apps to make sure that everything is fully loaded. The event is also notified if the apps are reloaded externally or over the Engine.reloadApps function.
Script.register("Engine.OnStarted", "MyApp.handleOnStarted")
Engine.AsyncFunction
Executes a CROWN function call in an underlying separate thread. There is one thread per AsyncFunction instance. Multiple launches on an AsyncFunction instance are queued up and executed after each other. This is useful to execute functions in parallel to better benefit from multiple cores available on the target hardware. Every function launch returns a Future-handle which identifies the function call. The results can be retrieved by calling the blocking function "wait" on the Future-handle or by registering to the event "OnFinished" to retrieve the function results asynchronously.
Functions
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
-- Create a simple async function call to a handle-based function and wait for its result:
asyncHandle = Engine.AsyncFunction.create()
asyncHandle:setFunction("Algo.function", algoHandle)
futureHandle = asyncHandle:call(p1, p2, p3)
r1, r2, r3 = futureHandle:wait()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
launch()
Starts a new call on the async handle with the specified parameters. This function directly returns a handle to an Engine.AsyncFunction.Future instance. Use this Future instance to wait for the function to be completed and get their result. Alternatively register to the "OnFinished" event to get the future objects notified there for each completed call. Multiple calls can be spawned at once. They are executed after each other.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
param1 |
AUTO |
First parameter for the async function call (optional) |
param2 |
AUTO |
second parameter for the async function call (optional) |
param3 |
AUTO |
third parameter for the async function call (optional) |
param4 |
AUTO |
fourth parameter for the async function call (optional) |
param5 |
AUTO |
fifth parameter for the async function call (optional) |
param6 |
AUTO |
sixth parameter for the async function call (optional) |
param7 |
AUTO |
seventh parameter for the async function call (optional) |
| Name | Type | Description |
|---|---|---|
futureHandle |
HANDLE |
The future handle to wait for the result of the async function call. Can be nil if there was an internal error while launching the function call or no function was set. |
Engine.AsyncFunction.launch(handle, param1, param2, param3)
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
setFunction()
Sets the target CROWN function name to call in the async function call execution. If the CROWN function is handle based, the handle can be passed as second parameter to this function, so that it is automatically set as first parameter for every function call. The handle is hold as long as the AsyncFunction exists.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
functionName |
STRING |
The function name which is called by this async function instance |
functionHandle |
HANDLE |
The optional handle which is automatically set as first parameter to every function call. The handle is held as long as the AsyncFunction exists. |
-- Static function:
Engine.AsyncFunction.setFunction(handle, "Algo.function")
-- Handle based function:
Engine.AsyncFunction.setFunction(handle, "Algo.function", algoHandle)
Events
OnFinished
This event is triggered on every function async call completion. The future handle is passed as parameter to get the function result. This is useful to receive the function results asynchronously instead of using the blocking Future.wait function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the channel |
futureHandle |
HANDLE |
The future object identifying the function call |
Engine.AsyncFunction.register(handle, "OnFinished", "handleResult")
Engine.AsyncFunction.Future
Is returned by the Engine.AsyncFunction.launch function to control the async function execution like to wait for the result. To cancel a queued up function execution, call the abandon function.
Overview
Functions
abandon()
Throws the async function execution and its result away. If the function execution is still queued, it will not be executed. If it is currently already running, the result of it will be abandoned.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
Engine.AsyncFunction.Future.abandon(futureHandle)
isFailed()
If the function call is finished, this function can be used to check, if there was an error calling the function asynchronously. A fail might happen, if the function to be called was not valid (not served) or the function parameters/return values were not correct.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
isFailed |
BOOL |
True if the function execution was failed. False if called successfully or not finished. |
isFailed = Engine.AsyncFunction.Future.isFailed(futureHandle)
isFinished()
Can be used to poll if the async function execution is finished.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
isFinished |
BOOL |
True if the function execution is finished. False if not. |
bIsFinished = Engine.AsyncFunction.Future.isFinished(handle)
wait()
Blocks and waits until the corresponding async function call finishes with optional timeout. Returns the result values of the function which was called asynchronously.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
timeoutMs |
INT |
The time in ms to wait for the function call to finish |
| Name | Type | Description |
|---|---|---|
result1 |
AUTO |
First result of the async function call (optional) |
result2 |
AUTO |
second result of the async function call (optional) |
result3 |
AUTO |
third result of the async function call (optional) |
result4 |
AUTO |
fourth result of the async function call (optional) |
result5 |
AUTO |
fifth result of the async function call (optional) |
result6 |
AUTO |
sixth result of the async function call (optional) |
result7 |
AUTO |
seventh result of the async function call (optional) |
res1, res2, res3 = Engine.AsyncFunction.Future.wait(handle)
Engine.Event
This is a generic block to map to an flow input or output event. It can register to events so that it can be used as input block, or it can notify an event so that it can be used as output block. It supports level and dirac signals.
Functions
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
handle = Engine.Event.create()
notify()
Notifies the specified event name. The event has to be added by the user to the manifest.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
|
signal |
BOOL |
The level/Dirac signal which triggers the event notify. |
Engine.Event.notify(handle, signal)
setEventName()
Name of the event to which the block registers to (OnEvent-event) or which the block notifies (notify-function). The event has to exist in the manifest in both cases. If it is a level-based event, it must have one bool parameter declared in the manifest. If it is a dirac-based event, it must have no parameter declared in the manifest.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
|
eventName |
STRING |
Engine.Event.setEventName(handle, eventName)
Events
OnEvent
Register to the specified event name and provides its occurrences as signal. If the event has no bool parameter, it is a dirac event. if the event has a bool parameter, it is a level event.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
|
signal |
BOOL |
The level/Dirac signal which is triggered by every event occurrence. If registered event has a bool parameter, the value is provided as level. |
Engine.Event.OnEvent(handle, signal)
Engine.EventBinding
Serves a new event and allows binding to an existing event including mapping the parameters to the new event notify. This is useful e.g. to bind handle based events to a static events and allow registration to them from a Flow block, but still configure it conveniently from a script.
Overview
Functions
bindParameters()
Adds parameter binding definitions. Could be called several times and adds them to the already bound ones. If not called at all, the parameters are directly mapped. The binding is specified from the registered event to the binding served event. A binding definition could be a position info or any other fix value. A position binding definition is done as string with a "$" as prefix like "$1". A position binding definition could be also the manifest parameter name of the served event. A fix value binding could be any CROWN type. If it should be a string starting with "$", then the first $ needs to be escaped to don’t be interpreted as position binding.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
binding1 |
AUTO |
One binding definition |
binding2 |
AUTO |
second binding definition (optional) |
binding3 |
AUTO |
third binding definition (optional) |
binding4 |
AUTO |
fourth binding definition (optional) |
binding5 |
AUTO |
fifth binding definition (optional) |
binding6 |
AUTO |
sixth binding definition (optional) |
binding7 |
AUTO |
seventh binding definition (optional) |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if binding was correctly specified and is added |
-- Maps to the target event:
-- second parameter of the event notify as first parameter
-- first parameter of the event notify as second parameter
-- integer value "1" as third parameter
-- content of lua variable "obj"
-- boolean value "true"
Engine.EventBinding.bindParameters(handle, "$2", "$1", 1, obj, true)
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
-- Create a simple binding to a handle-based event binding:
handle = Engine.EventBinding.create()
handle:setEvent("Provider.OnSomeEvent", providerHandle) -- The providerHandle is the handle to the sample provider "Provider.OnSomeEvent"
-- Serve the new event. After that the event is directly active and will be thrown if the bound event is thrown:
handle:serve("MyCrown.OnMyEvent")
getNotifyFunction()
Returns the function name which is served and can be called to trigger manually a notify on the served event. This function name is also used internally to register at the bound event. Might be useful to trigger event notifies manually.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
servedFunction |
STRING |
The function name of the function to notify the event. |
eventNotifyFuncName = Engine.EventBinding.getNotifyFunction(handle)
serve()
Serves a new event with the binding and returns true if successfully served. After this call the event can be registered by others and might get directly notified. If a event name is specified, the event must be available in the manifest. If no event name is specified, it generates an unique one and returns it. This is useful to directly bind a event notify without having it in the manifest.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
serveEventName |
STRING |
The event name including the crown name which should be served by this binding |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successfully served. False if already served by someone else |
genServedEventName |
STRING |
If no event name was specified as parameter, a generated unique one is returned |
Engine.EventBinding.serve(handle, "MyCrown.OnMyEvent")
setEvent()
Sets the bound event name to register to. If the event is handle based, the handle can be passed as second parameter to this function, so that the binding is done on the event on that handle. If a handle is set, the bindParameters function operates only on the event parameters after the handle. The handle is hold as long as the EventBinding exists.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
eventName |
STRING |
The event name which is used for registration |
eventHandle |
HANDLE |
The optional handle on which the event should be registered. The handle is hold as long as the EventBinding exists. |
-- Static event:
Engine.EventBinding.setEvent(handle, "Provider.OnEvent")
-- Handle based event:
Engine.EventBinding.setEvent(handle, "Provider.OnEvent", providerHandle)
Engine.FunctionBinding
Serves a new function and allows binding to an existing function including mapping the parameters and results to the target function call. This is useful e.g. to bind handle based function to a static function and allow calling them from a Flow block, but still configure it conveniently from a script.
Overview
Functions
bindParameters()
Adds parameter binding definitions. Could be called several times and adds them to the already bound ones. If not called at all, the parameters are directly mapped. The binding is specified from the binding served function to the target function. A binding definition could be a position info or any other fix value. A position binding definition is done as string with a "$" as prefix like "$1". A position binding definition could be also the manifest parameter name of the served function. A fix value binding could be any CROWN type. If it should be a string starting with "$", then the first $ needs to be escaped to don’t be interpreted as position binding.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
binding1 |
AUTO |
One binding definition |
binding2 |
AUTO |
second binding definition (optional) |
binding3 |
AUTO |
third binding definition (optional) |
binding4 |
AUTO |
fourth binding definition (optional) |
binding5 |
AUTO |
fifth binding definition (optional) |
binding6 |
AUTO |
sixth binding definition (optional) |
binding7 |
AUTO |
seventh binding definition (optional) |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if binding was correctly specified and is added |
-- Maps to the target function:
-- second parameter of the function call as first parameter
-- first parameter of the function call as second parameter
-- integer value "1" as third parameter
-- content of lua variable "obj"
-- boolean value "true"
Engine.FunctionBinding.bindParameters(handle, "$2", "$1", 1, obj, true)
bindResults()
Adds result binding definitions. Could be called several times and adds them to the already bound ones. If not called at all, the parameters are directly mapped. The binding is specified from the target function to the binding served function. A binding definition could be a position info or any other fix value. A position binding definition is done as string with a "$" as prefix like "$1". A position binding definition could be also the manifest result name of the target function. A fix value binding could be any CROWN type. If it should be a string starting with "$", then the first $ needs to be escaped to don’t be interpreted as position binding.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
binding1 |
AUTO |
One binding definition |
binding2 |
AUTO |
second binding definition (optional) |
binding3 |
AUTO |
third binding definition (optional) |
binding4 |
AUTO |
fourth binding definition (optional) |
binding5 |
AUTO |
fifth binding definition (optional) |
binding6 |
AUTO |
sixth binding definition (optional) |
binding7 |
AUTO |
seventh binding definition (optional) |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if binding was correctly specified and is added |
Engine.FunctionBinding.bindResults(handle, "$2", "$1", 1, obj, true)
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
-- Create a simple binding to a handle-based function binding and register it at a provider:
handle = Engine.FunctionBinding.create()
handle:setFunction("Algo.process", algoHandle) -- The algoHandle is the handle to the sample function "Algo.process"
-- register the handle function at a provider:
SomeProvider.register(provHandle, "OnSomeEvent", handle:serve() )
lock()
Locks all further function calls and makes them return instead of calling the target function. This is useful e.g. to reconfigure handle which is bound to the function call. Attention: Take care to keep the locking time as less as possible.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
Engine.FunctionBinding.lock(handle)
serve()
Serves a new function with the binding and returns true if successfully served. After this call the function can be called by others. If a function name is specified, the function must be available in the manifest. If no function name is specified, it generates an unique one and returns it. This is useful to directly bind a function call without having it in the manifest.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
serveFuncName |
STRING |
The function name including the crown name which should be served by this binding |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successfully served. False if already served by someone else |
genServedFuncName |
STRING |
If no function name was specified as parameter, a generated unique one is returned |
Engine.FunctionBinding.serve(handle, "MyCrown.newFunction")
setFunction()
Sets the target function name to call. If the function is handle based, the handle can be passed as second parameter to this function, so that it is automatically set as first parameter for every function call. If a handle is set, the bindParameters function operates only on the function parameters after the handle, so the handle is implicitly added every time. The handle is hold as long as the FunctionBinding exists.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
functionName |
STRING |
The function name which is called by this binding |
functionHandle |
HANDLE |
The optional handle which is automatically set as first parameter to every function call. The handle is hold as long as the FunctionBinding exists. |
-- Static function:
Engine.FunctionBinding.setFunction(handle, "Algo.function")
-- Handle based function:
Engine.FunctionBinding.setFunction(handle, "Algo.function", algoHandle)
unlock()
Sets the target function to call.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
Engine.FunctionBinding.unlock(handle)
Engine.SyncEvent
Registers for the specified event and queues up all event occurrences. The user can synchronously wait for the event occurrence and their event parameters. There is an internal queue used which queues all events up. This is useful if the user needs to get the status of an event at a specified position during processing.
Overview
Functions
clear()
Clears all currently queued events. Pay attention that directly during returning from this function there might be events already added again.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
Engine.SyncEvent.clear(handle)
close()
Closes the internal queue and removes the registrations on the event. All currently queued events are discarded.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
Engine.SyncEvent.close(handle)
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
-- Create a simple sync event and
handle = Engine.SyncEvent.create()
handle:setEvent("Provider.OnEvent", provHandle)
handle:open()
r1, r2, r3 = handle:wait()
getSize()
Returns the current number of queued calls. Pay attention that directly during returning from this function there might be events already added again.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
queueSize |
INT |
The current number of queues which are queued in the internal queue |
local queueSize = Engine.SyncEvent.getSize(handle)
open()
Opens the internal queue by registering for the event which was set before. After this call the events are received and queue internally up. Returns true if the it was successfully registered and opened. Additionally it returns the internal served function name which also can be used manually by the user to enqueue the event.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered and opened. False if e.g. the event handle was not valid and registering was not possible or the event name was not valid |
enqueueFunctionName |
STRING |
If successfully opened, the function name is returned here to manually enqueue to the event queue or register at further events |
bSuccess, enqueueFunc = Engine.SyncEvent.open(handle)
poll()
Polls and returns the event parameters if there is already an event queued. Returns nothing if there was no event queued.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
result1 |
AUTO |
First result of the async function call (optional) |
result2 |
AUTO |
second result of the async function call (optional) |
result3 |
AUTO |
third result of the async function call (optional) |
result4 |
AUTO |
fourth result of the async function call (optional) |
result5 |
AUTO |
fifth result of the async function call (optional) |
result6 |
AUTO |
sixth result of the async function call (optional) |
result7 |
AUTO |
seventh result of the async function call (optional) |
setDiscardIfFull()
Sets the behaviour for adding events to the queue if the queue is full. Per default the oldest element is discarded. To discard the newest to be added element, call this function with parameter true.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
bDiscardIfFull |
BOOL |
Set to true to discard the newest item which is currently added instead of discarding the oldest element |
Engine.SyncEvent.setDiscardIfFull(handle, true)
setEvent()
Sets the event name to register to. If the event is handle based, the handle can be passed as second parameter to this function, so that the event is registered at the handle. The handle is hold as long as the SyncEvent exists. This function is also optional. If not called, the user can directly use the open function and use the returned function name to manually enqueue to the queue or register manually at events.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
eventName |
STRING |
The event name which is used for registration |
eventHandle |
HANDLE |
The optional handle on which the event should be registered. The handle is hold as long as the SyncEvent exists. |
-- Static event:
Engine.SyncEvent.setEvent(handle, "Provider.OnEvent")
-- Handle based event:
Engine.SyncEvent.setEvent(handle, "Provider.OnEvent", providerHandle)
setMaxQueueSize()
Sets the maximum queue size of the internal event queue. Per default the queue is set to infinite size (=0). If the max queue size is reached, the oldest element is discarded per default. To change that behaviour use the setDiscardIfFull-Function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
maxQueueSize |
INT |
The max number of events to queue. Per default 0 (=infinite) |
Engine.SyncEvent.setMaxQueueSize(handle, 10)
wait()
Blocks and waits until there is an event in the queue with optional timeout. Returns the parameter values of the event which was called received. If there is already an event queued, this function directly returns.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
timeoutMs |
INT |
The time in ms to wait for the function call to finish |
| Name | Type | Description |
|---|---|---|
result1 |
AUTO |
First result of the async function call (optional) |
result2 |
AUTO |
second result of the async function call (optional) |
result3 |
AUTO |
third result of the async function call (optional) |
result4 |
AUTO |
fourth result of the async function call (optional) |
result5 |
AUTO |
fifth result of the async function call (optional) |
result6 |
AUTO |
sixth result of the async function call (optional) |
result7 |
AUTO |
seventh result of the async function call (optional) |
Engine.WebServer
Provides functions for managing the engine’s embedded webserver.
Overview
Functions
setCrownEndpointEnabled()
Enable or disable the CROWN endpoint of the engine’s embedded webserver. If the endpoint is disabled REST and websocket communication on the URL 'api/crown' is no longer possible. Accessibility of the device page and communication via the 'api' URL is not affected, however.
| Name | Type | Description |
|---|---|---|
enabled |
BOOL |
True to enable, false to disable. |
Engine.WebServer.setCrownEndpointEnabled(false)
setEnabled()
Enable or disable the engine’s embedded webserver. If disabled the device page will not be accessible any more. REST and websocket communication is no longer possible.
| Name | Type | Description |
|---|---|---|
enabled |
BOOL |
True to enable, false to disable. |
Engine.WebServer.setEnabled(false)
FTPClient
Provides FTP/FTPS client functionality. Supports plain FTP and FTPS (FTP over SSL). FTPS can be configured to be used in explicit or implicit mode. SFTP (SSH File Transfer Protocol) is not supported. Important note: If your application design requires FTP connections to be kept open in idle mode you must use the setKeepAliveInterval() function to enable keep-alive. Otherwise the internal connection is closed, resulting in an unnecessary reconnect when performing the next active operation.
Keywords
Ethernet
See also
Overview
cd(), connect(), create(), deregister(), disconnect(), get(), getFile(), getLastError(), isConnected(), list(), mkdir(), put(), putFile(), register(), rename(), rm(), rmdir(), setCABundle(), setClientCertificate(), setConnectTimeout(), setHostnameVerification(), setInterface(), setIpAddress(), setKeepAliveInterval(), setMode(), setPassiveMode(), setPeerVerification(), setPort(), setSecurityProtocol(), setTransmitTimeout(), setVerbose()
Functions
cd()
Change the current directory on the server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
directory |
STRING |
Directory to change to. Can be a relative or absolute path in FTP path notation. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if directory has been changed successfully, false if an error occurred |
success = FTPClient.cd(handle, "/absolute/path")
connect()
Connect to a FTP server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
login |
STRING |
User name for login. |
password |
STRING |
Login password. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if connection is established, false if an error occurred |
success = FTPClient.connect(handle, "user", "password")
create()
Creates a new FTP client instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
handle = FTPClient.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
disconnect()
Disconnect an open connection to a FTP server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if connection is closed, false if an error occurred |
success = FTPClient.disconnect(handle)
get()
Download a file from the server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
filename |
STRING |
Target name of the file to download. Can be a relative or absolute path in FTP path notation. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if the file has been downloaded successfully, false if an error occurred. |
data |
BINARY |
Content of the file. |
success, data = FTPClient.get(handle, "/path/to/file")
getFile()
Download a file from the server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
remoteSource |
STRING |
Target name of the file to download. Can be a relative or absolute path in FTP path notation. |
localDestination |
STRING |
Destination path of the file to download. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if the file has been downloaded successfully, false if an error occurred. |
success = FTPClient.getFile(handle, "/path/to/file", "private/file")
getLastError()
Get information about the last FTPClient method invocation. Returns error code and error text. In case communication with the FTP server has taken place the FTP server code is delivered as code. This might be a error code or a success code.See https://en.wikipedia.org/wiki/List_of_FTP_server_return_codes . In case a libcurl error occurs it is returned as negative value. See https://curl.haxx.se/libcurl/c/libcurl-errors.html
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
| Name | Type | Description |
|---|---|---|
errorCode |
INT |
Error code of the FTP server |
errorText |
STRING |
Additional information on the error |
errorCode, errorText = FTPClient.getLastError(handle)
isConnected()
Returns whether the FTP client is connected to a server
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
| Name | Type | Description |
|---|---|---|
connectStatus |
BOOL |
Is true if the connection exists |
connectStatus = FTPClient.isConnected(handle)
list()
List the content of a directory on the server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
directory |
STRING |
Directory to list. Can be a relative or absolute path in FTP path notation. |
onlyNames |
BOOL |
If true (default), the FTP command NLST is used and only the names of the directory entries are returned. If false, the FTP command LIST is used instead. LIST returns additional information about each file, but the format is server-specific. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if directory has been listed successfully, false if an error occurred |
directoryEntries |
STRING |
List of directory entries. |
success, directoryEntries = FTPClient.list(handle, "/absolute/path")
mkdir()
Create a directory on the server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
directory |
STRING |
Directory to create. Can be a relative or absolute path in FTP path notation. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if directory has been created successfully, false if an error occurred |
success = FTPClient.mkdir(handle, "/absolute/path")
put()
Upload a file to the server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
filename |
STRING |
Target name of the file to upload. Can be a relative or absolute path in FTP path notation. |
data |
BINARY |
Content of the file to upload. |
appendMode |
BOOL |
Append mode. If true, the data is appended to the file if it already exists, otherwise the file is created. Default is false. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if the file has been uploaded successfully, false if an error occurred. |
success = FTPClient.put(handle, "/path/to/file", data)
putFile()
Upload a file to the server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
remoteDestination |
STRING |
Target name of the file to upload. Can be a relative or absolute path in FTP path notation. |
localSource |
STRING |
Source path of the file to upload. |
appendMode |
BOOL |
Append mode. If true, the data is appended to the file if it already exists, otherwise the file is created. Default is false. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if the file has been uploaded successfully, false if an error occurred. |
success = FTPClient.putFile(handle, "/path/to/file", "resources/file")
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
rename()
Rename a file on the server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
filenameFrom |
STRING |
File to rename. Can be a relative or absolute path in FTP path notation. |
filenameTo |
STRING |
New filename. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if the file has been renamed successfully, false if an error occurred. |
success = FTPClient.rename(handle, "fileOld.txt", "fileNew.txt")
rm()
Remove a file on the server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
filename |
STRING |
File to remove. Can be a relative or absolute path in FTP path notation. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if the file has been removed successfully, false if an error occurred. |
success = FTPClient.rm(handle, "file.txt")
rmdir()
Remove a directory on the server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
directory |
STRING |
Directory to remove. Can be a relative or absolute path in FTP path notation. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if directory has been removed successfully, false if an error occurred |
success = FTPClient.rmdir(handle, "/absolute/path")
setCABundle()
Configures the certificate authority bundle to be used for verifying server certificates.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTPClient. |
bundleFile |
STRING |
Path to a certificate bundle in PEM format. |
FTPClient.setCABundle(handle, "private/CA.pem")
setClientCertificate()
Enables client authentication. A client certificate and a private key must be provided. The passphrase for the private key is optional. Supported file formats are PEM, DER and PKCS#12 (depending on SSL engine) for the client certificate and PEM and DER for the private key. The format is selected by inspecting the extension of the provided file. If no valid extension is specified the engine defaults to PEM format.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTPClient. |
certificateFile |
STRING |
Path to a certificate file in PEM/DER/PKCS#12 format. |
keyFile |
STRING |
Path to file containing the client’s private key in PEM/DER format. |
passphrase |
STRING |
Optional passphrase for the private key. |
FTPClient.setClientCertificate(handle, "private/cert.pem", "private/privateKey.pem", "mypassphrase")
setConnectTimeout()
Configures the connect/accept timeout.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
timeoutMs |
INT |
Timeout for connect/accept in milliseconds. Default is 5000ms. |
FTPClient.setConnectTimeout(handle, 1000)
setHostnameVerification()
Enables/disables hostname verification. This can be useful if the site to connect to uses a different host name than what is mentioned in the server certificate commonName (or subjectAltName) fields. Disabling this verification makes the connection less secure.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTPClient. |
enabled |
BOOL |
True to enable hostname verification, false to disable. Default is enabled. |
FTPClient.setHostnameVerification(handle, false)
setInterface()
Sets the interface to use for connecting. Before setting the first interface is used.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
ifName |
ENUM EthernetInterfaces |
One of the available interfaces |
FTPClient.setInterface(handle, "ETH1")
setIpAddress()
Configures the ip address to connect to.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
ipAddress |
STRING |
IP address of the server. |
FTPClient.setIpAddress(handle, "192.168.0.20")
setKeepAliveInterval()
Activates sending of keep-alive commands with a given time periode. A time periode of 0 disables sending of keep-alive commands. Can be executed before or during a FTP connection.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
sec |
INT |
Time periode in seconds. |
FTPClient.setKeepAliveInterval(handle, 30)
setMode()
Sets the mode for following file transfers.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
mode |
ENUM TransferMode |
Transfer mode that is to be set. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if mode has been set successfully, false if an error occurred |
success = FTPClient.setMode(handle, "binary")
setPassiveMode()
Enable or disable the FTP passive mode. This can be done before connecting to a FTP server. Disabled passive mode is the default setting of the FTPClient
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
state |
BOOL |
True set passive mode. False set active mode |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if the operation was successful. If false, use getLastError for more details on the error |
success = FTPClient.setPassiveMode(handle, true)
setPeerVerification()
Enables/disables peer verification. This can be useful when connecting to a site that is not using a certificate signed by one of the certs in the CA bundle. Disabling this verification makes the connection A LOT LESS SECURE.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTPClient. |
enabled |
BOOL |
True to enable peer verification, false to disable. Default is enabled. |
FTPClient.setPeerVerification(handle, false)
setPort()
Configures the port for the control connection.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
port |
INT |
Port for control connection. Default is 21. |
FTPClient.setPort(handle, 1234)
setSecurityProtocol()
Sets the security protocol to use.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTPClient. |
protocol |
ENUM SecurityProtocol |
Security protocol and mode to use. Default is none (plain FTP without TLS). To use FTPS, a certificate authority bundle needs to be configured. See function setCABundle. |
FTPClient.setSecurityProtocol(handle, "FTPS_EXPLICIT")
setTransmitTimeout()
Configures the transmit timeout.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
timeoutMs |
INT |
Timeout for transmits in milliseconds. If not set the value of the connect timeout is used. |
FTPClient.setTransmitTimeout(handle, 5000)
setVerbose()
Tell the FTPClient to print log messages during the transfer. This includes the debug output of the curl library This method must be called before connecting to the FTP server.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
state |
BOOL |
True set the FTPClient in verbose state |
FTPClient.setVerbose(handle, true)
Events
OnDisconnected
Event that is thrown when the FTPServer disconnects the connection
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP client |
FTPServer
Provides FTP server functionality. Create a new FTP server instance by calling the create function first. You may set the server port and the maximum number of connections via the setServerPort and setMaxConnections functions. Default is 21 for the server port and 10000 connections. Users may be added or removed using the addUser and removeUser functions. Login names must be unique per FTP server instance. Please note that you must add at least one user, even if you want anonymous login. Leave the password empty in that case. The data port range for PASV mode may be set with the setDataPortRange function. Several other parameters can be changed using the associated set functions, but meaningful default values have been selected already. Start the server using the start function and stop it (if needed) by calling stop.
Keywords
Ethernet
See also
Overview
Functions
addUser()
Add a user account
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
login |
STRING |
Login name for the user account |
password |
STRING |
Password for the user account. Leave empty to not check the password. |
startDirectory |
STRING |
Root directory for the user account. Only paths relative to the app home directory are allowed. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if user was added, false if an error occurred |
success = FTPServer.addUser(handle, "anonymous", "", "public")
create()
Creates a new FTP server instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
handle = FTPServer.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
removeUser()
Remove a user account
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
login |
STRING |
Login name of the user account which is to be removed |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if user was removed, false if an error occurred |
success = FTPServer.removeUser(handle, "anonymous")
setCheckPassDelay()
Configure the forced delay between subsequent login attempts in milliseconds
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
delay |
INT |
Delay between subsequent login attempts in milliseconds. Default is 500. |
FTPServer.setCheckPassDelay(handle, 5000)
setDataPortRange()
Set the range of data ports available for PASV mode port selection
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
rangeBegin |
INT |
First port of range (inclusive). |
rangeEnd |
INT |
Last port of range (inclusive). |
FTPServer.setDataPortRange(handle, 5000, 6000)
setInterface()
Sets the interface to use for connecting.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
ifName |
ENUM EthernetInterfaces |
One of the available interfaces |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if interface was set successfully, false if an error occurred |
FTPServer.setInterface(handle, "ETH1")
setMaxConnections()
Configures the maximum number of connections allowed on the control port.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
connections |
INT |
Maximum number of connections that is allowed. Default is 10000. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if max connections were set successfully, false if an error occurred |
success = FTPServer.setMaxConnections(handle, 100)
setServerPort()
Configure the port number for the FTP server’s control connection.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
port |
INT |
Number of the port to listen on. Default is 21. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true if server port was set successfully, false if an error occurred |
success = FTPServer.setServerPort(handle, 33)
setTransferBufferSize()
Sets the size of the transfer buffer used for data connections
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
bufferSize |
INT |
Buffer size for data connection transfers. Default is 32768. |
FTPServer.setTransferBufferSize(handle, 10000)
start()
Start the FTP server
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true when the FTP server is running, false if an error occurred. |
success = FTPServer.start(handle)
stop()
Stop the FTP server
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the FTP server |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true when the FTP server has been stopped successfully, false if an error occurred. |
FTPServer.stop(handle)
Events
OnStore
The event which is triggered after a file has been uploaded.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
This is a handle event and must be registered on the handle |
fileName |
STRING |
The name of the file that has been uploaded. |
filePath |
STRING |
The path where the file has been put. |
FieldBus
Provides field bus access. This API is intended for field bus slave devices and allows them exchange data with a PLC. It works for all field bus protocols like PROFINET, EtherNet/IP and EtherCAT. Which field bus protocols are actually available depends on the device. How to enable the field bus functionality or select a specific protocol is also device specific. Some devices offer these settings via the SOPAS Engineering Tool. There is no possibility to select the protocol via this API. To integrate the device into PLC projects you need an appropriate device description file. These are available via the SICK support portal. - PROFINET: GSDML file - EtherNet/IP: EDS file - EtherCat: ESI file Devices which implement this API offer two independent ways to communicate process data with a PLC: - For each direction (output from PLC to device and input from device to PLC), there is a field "ControlBits" with a length of 16 bits. These fields can be used freely by your application, there is no predefined meaning for the individual bits. - The rest of the cyclic process data can be used in two different modes: - In Confirmed Messaging mode, it is used as a transfer channel for the SICK Confirmed Messaging protocol. This protocol allows to send arbitrary strings in both directions. The protocol can also handle strings that are longer than the size of the cyclic process data. This works by splitting them up in several fragments which are transferred and acknowledged sequentially. To use this channel from the PLC side, SICK offers ready-to-use function blocks for Confirmed Messaging for various PLCs. - In Raw mode, the user receives and sets the process data directly without any protocol.
Overview
Functions
close()
Stops communication to the field bus
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The FieldBus handle |
FieldBus.close(busHandle)
create()
Creates a new instance. This can fail if field bus functionality is disabled in the device. Some devices offer a switch to enable and select the type of field bus via the SOPAS Engineering Tool.
| Name | Type | Description |
|---|---|---|
mode |
ENUM CreateMode |
Optional create mode. Default is 'AUTOMATIC_OPEN'. |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The new FieldBus. nil if FieldBus is disabled. |
busHandle = FieldBus.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
open()
Starts the communication to the field bus. This function only has to be called when the handle was created with CreateMode "EXPLICIT_OPEN". Otherwise, open is done automatically on handle create.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The FieldBus handle |
FieldBus.open(busHandle)
readControlBitsIn()
Gets the current value of the control bits transmitted to the PLC
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The FieldBus handle |
| Name | Type | Description |
|---|---|---|
controlBitsIn |
INT |
the control bits |
local controlBitsIn = FieldBus.readControlBitsIn(busHandle)
readControlBitsOut()
Gets the current value of the control bits received from the PLC
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The FieldBus handle |
| Name | Type | Description |
|---|---|---|
controlBitsOut |
INT |
the control bits |
local controlBitsOut = FieldBus.readControlBitsOut(busHandle)
register()
This function is used to register for events from the FieldBus
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
|
eventname |
STRING |
The event to register to |
callback |
STRING |
Function name to call when an event occurs |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
Fieldbus.register(handle, 'OnNewData', callback)
setMode()
Sets the transmission mode. Default is "CONFIRMED_MESSAGING".
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The FieldBus handle |
mode |
ENUM TransmissionMode |
Transmission mode |
FieldBus.setMode(busHandle, "RAW")
transmit()
Transmits data through the field bus to the PLC. This function does not affect the control bits, only the rest of the cyclic process data. Behavior depends on transmission mode (see function setMode): In mode RAW: Directly set the parameter data as cyclic process data. If data is too long to be transmitted according to the current PLC connection settings, the data is trunacated. This function returns the actual number of bytes that were transmitted. In mode CONFIRMED_MESSAGING: - If there is no connection to a PLC, the function fails and returns immediately with return value 0. - If there is a connection to a PLC, the function returns after transmission of the data starts. The function might block for up to 10 seconds if it is not possible to start sending immediately. This is the case if other data from previous calls to transmit is still being transmitted or if the PLC did not confirm a previous transmit yet. If it is not possible to start sending in 10 seconds, the function fails with return value 0. - The function does not wait till the transmission of the data is complete. - The function does not wait for the confirmation from the PLC.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The FieldBus handle |
data |
BINARY |
The data which is to be transmitted. Up to 4094 bytes can be transmitted with a single call. If the size is larger, only the first 4094 bytes will be transmitted. |
| Name | Type | Description |
|---|---|---|
numberOfBytesTransmitted |
INT |
Number of bytes transmitted; 0 if transmit failed. |
bytesTransmitted = FieldBus.transmit(busHandle, "Hello PLC")
writeControlBitsIn()
Sets and transmits the value of the control bits to the PLC
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The FieldBus handle |
controlBits |
INT |
The control bits to write |
bitMask |
INT |
The bitmask to use |
FieldBus.writeControlBitsIn(busHandle, controlBits, bitMask)
Events
OnControlBitsOutChanged
This event is thrown when the control bits set by the PLC have changed.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The FieldBus handle |
ctrlBits |
INT |
ctrl bits out |
OnNewData
This event is thrown when new data has been received from the PLC through the field bus.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The FieldBus handle |
data |
BINARY |
File
Provides file operation functions. The application has access to different folders on the filesystem of the device. There are the following app related paths: - The "resources" folder is read-only and can be used to read app resources like parameter files, images etc. - The "private" directory can be used to store persistent app data privately. This data is backup-ed with together with the app. - The "public" directory can be used for shared access with other applications. All applications have access to this folder. The "private" and "public" folders should only be used as persistent storage and NOT to continuously process data. ATTENTION: The underlying hardware could get broken if overused! Consider to use API functions which don’t use files or use the ram filesystem mounted drive of the device. Additionally it is possible to access the mounted drives of a device. Which mounted drives are available is defined by the device in a CROWN enum named "MountedDrives". E.g. there could be a path "/usb/0" for the first USB drive, or "/sdcard/0" for the first SD Card drive.
Overview
Functions
close()
Closes a file identified by a handle. If not explicitly called, the file is automatically closed on destruction of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The filehandle of an opened file. |
File.close(handle)
copy()
Copies the specified file or full path to another file or path. If the target file exists it is overwritten. If the target path exists it is integrated in the target structure.
| Name | Type | Description |
|---|---|---|
fileSourcePath |
STRING |
The path to copy from |
fileTargetPath |
STRING |
The path to copy to |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successful, false if source path does not exist or cannot overwrite new files. |
local success = File.copy("/private/sourcefile.txt", "/private/targetfile.txt")
del()
Deletes a file or folder specified by a path. The path must start with "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). Deleting the "public", "private" or mounted drive itself is not allowed and returns false. Their contents can be deleted by iterating on their elements.
| Name | Type | Description |
|---|---|---|
fileName |
STRING |
The path to the file/folder that is to be deleted |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
true if success |
local success = File.del("/private/myfile.txt")
exists()
Checks if the given path or file exists. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
| Name | Type | Description |
|---|---|---|
fileName |
STRING |
The path to the file/folder that is to be checked |
| Name | Type | Description |
|---|---|---|
result |
BOOL |
true if success |
local bExists = File.exists("/private/myfile.txt")
extractPathElements()
Splits the specified path string into its elements path, file basename and file extension.
| Name | Type | Description |
|---|---|---|
filePath |
STRING |
The path string to extract from |
| Name | Type | Description |
|---|---|---|
path |
STRING |
The path of the file |
basename |
STRING |
The base name of the file |
extension |
STRING |
The file extension of the file |
local path, basename, extension = File.extractPathElements("/private/thefile.txt")
getDiskFree()
Returns the remaining space of a specific path.
| Name | Type | Description |
|---|---|---|
path |
STRING |
The name of the path to get the free space from. |
| Name | Type | Description |
|---|---|---|
freeBytes |
INT |
The available bytes in the path. |
local free = File.getDiskFree("/public")
getDiskUsage()
Returns the usage of a specific path.
| Name | Type | Description |
|---|---|---|
path |
STRING |
The path to get the usage from. |
| Name | Type | Description |
|---|---|---|
usedBytes |
INT |
The bytes used in the path. |
local usage = File.getDiskUsage("/public")
getPath()
Returns the path of the file handle with which it was opened.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The filehandle of an opened file. |
| Name | Type | Description |
|---|---|---|
filePath |
STRING |
The path to the file that was opened. Nil if file handle is not open. |
local path = File.getPath(handle)
isdir()
Checks if the given path is a folder. The path must start with "resources", "public", "private"or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
| Name | Type | Description |
|---|---|---|
fileName |
STRING |
The path to the file/folder that is to be deleted |
| Name | Type | Description |
|---|---|---|
result |
BOOL |
true if success |
local isDir = File.isdir("/private/myfile.txt")
list()
Lists all files and subdirectories in the specified directory non-recursively. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). Returns a list of file and directory names in the specified path.
| Name | Type | Description |
|---|---|---|
filePath |
STRING |
The path to the folder to list |
filter |
STRING |
A string to filter the results of the listing. Wildcards can be used. |
| Name | Type | Description |
|---|---|---|
list |
STRING |
The list of file and directory names. Nil if specified filePath does not exist or is not a directory. |
local fileList = File.list("/private/", "*.png")
listRecursive()
Lists all files and subdirectories in the specified directory recursively (without empty folders). The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). Returns a list of file and directory names in the specified path.
| Name | Type | Description |
|---|---|---|
filePath |
STRING |
The path to the folder to list |
| Name | Type | Description |
|---|---|---|
list |
STRING |
The list of file and directory names including the relative path to the specified directory. Nil if specified filePath does not exist or is not a directory. |
local fileList = File.listRecursive("/private/")
mkdir()
Creates a new folder specified by a path. The path must start with "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
| Name | Type | Description |
|---|---|---|
fileName |
STRING |
The path to the folder that is to be created |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
true if success or already exists. false if not possible or is already a file. |
local success = File.mkdir("/private/myfolder")
move()
Moves the specified file or full path to another file or path. If the target file exists it is overwritten. If the target path exists it is integrated in the target structure. If moving fails, parts of the source path may still exist, and the target path may be inconsistent or incomplete.
| Name | Type | Description |
|---|---|---|
fileSourcePath |
STRING |
The path to move from |
fileTargetPath |
STRING |
The path to move to |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
true if success. false if source path does not exist or cannot overwrite new files. |
local success = File.move("/private/sourcefile.txt", "/private/targetfile.txt")
open()
Opens a file specified by a path and mode. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device). The mode specifies if it is for reading or writing and if it is in ASCII or binary mode (standard POSIX modes). The file is created if it does not exist and is opened for writing. Returns a handle if successful, which needs to be used for further file functions. Open for reading might fail if the file does not exist or is already opened for writing. Open for writing might fail if the file is already opened for reading or writing, or if the "resources" folder is opened for writing (which is read-only).
| Name | Type | Description |
|---|---|---|
filePath |
STRING |
The path to the file that is to be opened |
mode |
STRING |
Use "r" or "rb" for reading, "w" or "wb" for writing, "a" or "ab" for append; "b" means binary, without "b" the OS could change control characters like CR or LF. Same syntax like in C fopen() |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
An indicator for accessing the file. Is nil if failed. See File CROWN description for error info. |
local handle = File.open("/private/myfile.txt", "wb")
position()
Returns the current position of the file pointer.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The filehandle of an opened file. |
| Name | Type | Description |
|---|---|---|
position |
INT |
The current position of the file pointer. |
local position = File.position(handle)
read()
Reads data from a file identified by a handle. The number of bytes to read can be specified. Continuous calls to read continue to read at the current position. If a read returns a binary of size 0, then there is no more data to read.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The filehandle of an opened file. |
length |
INT |
The number of bytes to read. Read the whole file if not specified or zero. |
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The data which was read from the file. Is nil if the file isn’t opened. Binary size is 0 if there is nothing more to read. |
local data = File.read(handle, length)
seek()
Places the file pointer at the specified position. The next read will start at this position.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The filehandle of an opened file. |
position |
INT |
The position to jump to in the file. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if seeking in the file was successful. |
local success = File.seek(handle, 15)
size()
Returns the size of a file. The path must start with "resources", "public", "private" or with a mounted drive name like "ram", "usb" or "sdcard" (depends on the "MountedDrives" enum of the device).
| Name | Type | Description |
|---|---|---|
fileName |
STRING |
The path to the file |
| Name | Type | Description |
|---|---|---|
fileSize |
INT |
size of file |
local fileSize = File.size("/private/myfile.txt")
write()
Writes to a file identified by a handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The filehandle of an opened file. |
data |
BINARY |
The data to write into the file |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if the data was successfully written to the file. |
local success = File.write(handle, "Hello")
File.Archive
Contains functionality to pack/unpack files as an archive.
File.Archive.ZIP
File Archive functionality to work with ZIP files. An archiver instance works with one ZIP archive at a time. To handle multiple ZIPs at a time, create multiple instances of the archiver. Loaded or added files must exist and are kept locked by this API until the handle is destroyed or close function is called. Both inflated and deflated ZIP archives can be read. ZIP file writing supports only inflated archives.
Overview
Functions
add()
Adds a file or whole directory from the filesystem to the archive. The specified file needs to exist and is locked until this class loads another zip file or close function is called. If there is already a file or folder with that archive path, it is overwritten.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
sourceFilePath |
STRING |
The path to the file or directory which should be added. E.g. '/private/sourceFile.txt' |
archiveFilePath |
STRING |
The path in the archive to which the file or directory should be added. Must be a full file path including file name. Sub-directories are created automatically. Existing file is overwritten. Leave empty to add to root directory of the archive. E.g. 'archiveFolder/archiveFile.txt' |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully added the file. False if the file does not exist. |
local success = File.Archive.ZIP.add(handle, "/private/sourceFile.txt", "archiveFolder/archiveFile.txt")
create()
Creates a new ZIP archive instance to work on archives.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
local handle = File.Archive.ZIP.create()
del()
Deletes a file or whole directory (including added files all sub-directories) from the archive. If the archive is afterwards saved or serialized, the specified archive path will not be part of it.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
archiveFilePath |
STRING |
The path in the archive which should be deleted. E.g. 'archiveFolder/archiveFile.txt' |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deleted the file or folder. False if there was nothing found in the archive path to delete. |
local success = File.Archive.ZIP.del(handle, "archiveFolder/archiveFile.txt")
deserialize()
Loads a zip archive from the specified binary buffer. This is useful if zip file is already present in memory so that it does not need to be stored to file to load it. E.g. if the zip file content is directly received from a TCPIP client or similar.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
archiveBuffer |
BINARY |
The binary buffer containing the whole archive. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully loaded the zip. False if the buffer content is not valid or no zip file. |
local success = File.Archive.ZIP.deserialize(handle, buffer)
extract()
Extracts a file from the archive to the filesystem.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
archiveFilePath |
STRING |
The path in the archive from which the file or directory should be extracted. E.g. 'archiveFolder/archiveFile.txt'. Leave empty to extract whole archive. |
targetFilePath |
STRING |
The path to the file or directory which should be extracted to. Sub-directories are created automatically. E.g. '/private/targetFile.txt' |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully extracted the file. False if the file does not exist or could not extracted to the target path or password does not work on the file. |
local success = File.Archive.ZIP.extract(handle, "archiveFolder/archiveFile.txt", "/private/targetFile.txt")
getComment()
If an archive is loaded, return the current comment set on the loaded archive. If the setComment function was used, it still returns the comment of the loaded archive and not the one which is newly set.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
| Name | Type | Description |
|---|---|---|
comment |
STRING |
The comment text is set on the loaded archive. Nil if there is no loaded archive. |
list()
Lists the content from the current loaded archive. The paths are relative and therefore don’t start with a leading "/".
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
| Name | Type | Description |
|---|---|---|
content |
STRING |
List of file paths in the current loaded archive |
local fileList = File.Archive.ZIP.list(handle)
load()
Loads a zip archive from the specified file. The loaded file keeps locked until this class loads another zip file or close function is called. If loading fails a previously loaded zip file state is cleared.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
sourceFilePath |
STRING |
The path to the zip file that is to be loaded. E.g. '/private/load.zip' |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully loaded the zip. False if file does not exist or is no zip file |
local success = File.Archive.ZIP.load(handle, "/private/load.zip")
mkdir()
Creates an empty folder. If there is already a file or folder with that archive path, it is overwritten. Remember that files to be added don’t need a folder to be created first, so this function is only if there should be an empty folder in the archive. If it is a sub path, it creates the whole folder.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
archiveFilePath |
STRING |
The path in the archive which should be created as folder. E.g. 'archiveFolder/newFolder' |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully created the new folder. |
local success = File.Archive.ZIP.mkdir(handle, "archiveFolder/newFolder")
read()
Extracts a single file from the archive and returns it as binary buffer. This is useful if the file needs to be in memory so that it could be directly used for further processing. E.g. if the zip file is directly sent to TCPIP client or similar.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
archiveFilePath |
STRING |
The path in the archive from which the file or directory should be extracted. E.g. 'archiveFolder/archiveFile.txt' |
| Name | Type | Description |
|---|---|---|
fileBuffer |
BINARY |
The binary buffer containing the zip file. Nil on error if file does not exist or password does not work on the file. |
local buffer = File.Archive.ZIP.read(handle, "archiveFolder/archiveFile.txt")
save()
Saves the current zip file state to the specified file path. Any existing file is overwritten.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
targetFilePath |
STRING |
The path to which the zip file is saved. E.g. '/private/save.zip' |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully saved the zip file to the filesystem |
local success = File.Archive.ZIP.save(handle, "/private/save.zip")
serialize()
Returns the current zip file state as content of a binary buffer. This is useful if the zip file needs to be in memory so that it could be directly used for further processing. E.g. if the zip file content is directly sent to TCPIP client or similar.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
| Name | Type | Description |
|---|---|---|
archiveBuffer |
BINARY |
The binary buffer containing the whole archive. The buffer could be empty on error. |
local buffer = File.Archive.ZIP.serialize(handle)
setComment()
Sets the global archive comment text used for saving/serializing the archive.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
comment |
STRING |
The comment text which is set on the archive |
setCompression()
Sets the compression level to use for adding/writing new files to the archive. The deflate compression method is used. If not called, the default level is just to store the files without compression. The function can be called between add/write calls to change the compression level used for files. If not called before the last set value is used implicitly. Files, which are loaded from an existing archive, keep their compression and cannot be changed (Need to be removed and added again).
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
complevel |
ENUM Compression |
The level used for compression |
File.Archive.ZIP.setCompression(handle, "BEST")
setPassword()
Sets the password used for decryption/encryption during accessing and writing the archive. Only the load/save and deserialize/serialize functions use the current set password. If not called, there is no password used. The password is globally set for all operations for the whole archive content. It is NOT possible to set passwords per file. Also if the to be loaded file uses different passwords per file, it currently isn’t possible to be loaded.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
password |
STRING |
Sets the password used for accessing and writing the archive. If empty, not password is used. |
File.Archive.ZIP.setPassword(handle, "mypassword")
test()
Fully tests and verifies the currently loaded archive. Needs some time and fully reads the file. 1. Tests if the set password works with all files 2. Reads all content and verifies their CRC32 checksums 3. Verifies the file infos and the central directory
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
| Name | Type | Description |
|---|---|---|
valid |
BOOL |
True if the archive is valid. False if one validation step has failed or no archive is loaded. |
write()
Adds a single file from the specified binary buffer. This is useful if the file is already present in memory so that it does not need to be stored to a file to add it. E.g. if the zip file is directly received from a TCPIP client or similar. If there is already a file or folder with that archive path, it is overwritten.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle for the ZIP archiver |
fileBuffer |
BINARY |
The binary buffer containing the zip file. |
archiveFilePath |
STRING |
The path in the archive to which the file or directory should be added. Must be a full file path including file name. Sub-directories are created automatically. Existing file is overwritten. E.g. 'archiveFolder/archiveFile.txt' |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully added the file. |
local success = File.Archive.ZIP.write(handle, buffer, "archiveFolder/archiveFile.txt")
Halcon
Load Halcon procedures or operators and execute them. Native AppSpace input parameters are converted to Halcon types, and Halcon output parameters are converted to native Appspace types. The following conversions are supported: - Strings, floats and integers (correspond to Halcon control parameter tuple) - Vectors of strings, floats and integers (correspond to Halcon control parameter tuples) - Image (correspond to the Halcon iconic type Image) - Shape and Shape.Composite (correspond to the Halcon iconic type XLD) - Image.PixelRegion (correspond to the Halcon iconic type Region) - PointCloud (correspond to Halcon control parameters refering to an ObjectModel3D) - Mesh (correspond to Halcon control parameters refering to an ObjectModel3D with additional attributes 'triangles' and possibly 'point_normal_x', 'point_normal_y' and 'point_normal_z') Features: - A Halcon handle can be reused to load multiple procedures during its lifetime. - Input parameters that do not change between executions only need to be set once. That is, there is no need to call Halcon.setInteger(h, 'YourParam', 10) prior each call to Halcon.execute(h) if that parameter does not change. - Converting single-channel images as input for Halcon uses a shallow copy. Only multi-channel images (RGB) require a deep copy. - Returning images from HALCON always requires a deep copy. Limitation: The scripting engine does not support Halcons protected procedures feature. Please use the read protection property for the application from AppStudio instead. A first example: h = Halcon.create() Halcon.loadProcedure(h, '>sobel_amp') Halcon.setImage(h, 'Image', image) Halcon.setString(h, 'FilterType', 'sum_abs') Halcon.setInteger(h, 'Size', 3) r = Halcon.execute(h) i = Halcon.Result.getImage(r, 'EdgeAmplitude') This will load Halcons Sobel filter, process the input image image and return the result. Accessing Files and Directories: The Halcon scripting interface provides placeholders in order to enable Halcon scripts to access the applications 'resources', 'private' and 'public' folders and if available also storage mounted by usb, sdcard or ram disk. In Halcon, the following set of placeholders are available: - APPDATA_RESOURCES - APPDATA_PRIVATE - APPDATA_PUBLIC - APPDATA_SDCARD (if available) - APPDATA_USB (if available) - APPDATA_RAM (if available) These placeholders can be used within Halcon procedures to read and write data. E.g. the following syntax can be used for reading an OCR classifier: read_ocr_class_mlp(APPDATA_RESOURCES + 'Document_A-Z+_Rej.omc', OCRModel) Please note that these keywords must be used only within the corresponding operator scope. The following is not valid and will yield an error when loading a procedure: Path := APPDATA_RESOURCES + 'Document_A-Z+_Rej.omc' read_ocr_class_mlp(Path, OCRModel) The above syntax is required for all read and write operators in Halcon. The scripting interface restricts the usage of such operators to use one of these placeholders to access any data. Otherwise, the corresponding procedure will not be loaded. The following list of operators performing a read operation can use all placeholders: caltab_points, create_text_model_reader, disp_caltab, file_exists, find_caltab, find_marks_and_pose, get_prep_info_class_gmm, get_prep_info_class_mlp, get_prep_info_class_svm, get_prep_info_ocr_class_mlp, get_prep_info_ocr_class_svm, import_lexicon, list_files, read_aop_knowledge, read_bar_code_model, read_calib_data, read_cam_par, read_camera_setup_model, read_class_box, read_class_gmm, read_class_knn, read_class_mlp, read_class_svm, read_class_train_data, read_component_model, read_contour_xld_arc_info, read_contour_xld_dxf, read_data_code_2d_model, read_deformable_model, read_deformable_surface_model, read_descriptor_model, read_distance_transform_xld, read_fft_optimization_data, read_funct_1d, read_gray_se, read_image, read_kalman, read_matrix, read_measure, read_metrology_model, read_ncc_model, read_object, read_object_model_3d, read_object_model_3d_dxf, read_ocr, read_ocr_class_cnn, read_ocr_class_knn, read_ocr_class_mlp, read_ocr_class_svm, read_ocr_trainf, read_ocr_trainf_names, read_ocr_trainf_names_protected, read_ocr_trainf_select, read_ocv, read_polygon_xld_arc_info, read_polygon_xld_dxf, read_pose, read_region, read_sample_identifier, read_samples_class_gmm, read_samples_class_mlp, read_samples_class_svm, read_sampset, read_sequence, read_shape_model, read_shape_model_3d, read_sheet_of_light_model, read_surface_model, read_template, read_texture_inspection_model, read_training_components, read_tuple, read_variation_model, read_world_file, select_feature_set_trainf_knn, select_feature_set_trainf_mlp, select_feature_set_trainf_mlp_protected, select_feature_set_trainf_svm, select_feature_set_trainf_svm_protected, set_calib_data_calib_object, sim_caltab, trainf_ocr_class_box, trainf_ocr_class_knn, trainf_ocr_class_mlp, trainf_ocr_class_mlp_protected, trainf_ocr_class_svm, trainf_ocr_class_svm_protected, update_kalman The following list of operators performing a write operation can use all placeholders except APPDATA_RESOURCES and can thus not access the applications 'resources' folder: delete_file, gen_caltab, open_file, store_par_knowledge, write_aop_knowledge, write_bar_code_model, write_calib_data, write_cam_par, write_camera_setup_model, write_class_box, write_class_gmm, write_class_knn, write_class_mlp, write_class_svm, write_class_train_data, write_component_model, write_contour_xld_arc_info, write_contour_xld_dxf, write_data_code_2d_model, write_deformable_model, write_deformable_surface_model, write_descriptor_model, write_distance_transform_xld, write_fft_optimization_data, write_funct_1d, write_image, write_lut, write_matrix, write_measure, write_metrology_model, write_ncc_model, write_object, write_object_model_3d, write_ocr, write_ocr_class_knn, write_ocr_class_mlp, write_ocr_class_svm, write_ocr_trainf, write_ocr_trainf_image, write_ocv, write_polygon_xld_arc_info, write_polygon_xld_dxf, write_pose, write_region, write_sample_identifier, write_samples_class_gmm, write_samples_class_mlp, write_samples_class_svm, write_shape_model, write_shape_model_3d, write_sheet_of_light_model, write_surface_model, write_template, write_texture_inspection_model, write_training_components, write_tuple, write_variation_model The following list of operators are not supported and using them within a procedure will yield an error during load time of the procedure: close_framegrabber, close_io_channel, close_io_device, close_serial, close_socket, control_io_channel, control_io_device, control_io_interface, copy_file, get_current_dir, gnuplot_close, gnuplot_open_file, gnuplot_open_pipe, gnuplot_plot_ctrl, gnuplot_plot_funct_1d, gnuplot_plot_image, import, make_dir, open_compute_device, open_framegrabber, open_io_channel, open_io_device, open_serial, open_socket_accept, open_socket_connect, open_textwindow, protect_ocr_trainf, read_char, read_io_channel, read_serial, read_string, receive_data, receive_image, receive_region, receive_serialized_item, receive_tuple, receive_xld, release_all_compute_devices, release_compute_device, remove_dir, send_data, send_image, send_region, send_serialized_item, send_tuple, send_xld, set_io_channel_param, set_io_device_param, socket_accept_connect, system_call, test_access, write_io_channel, write_serial, write_string The following list of operators are allowed but they are executed as no-op: dev_clear_obj, dev_clear_window, dev_close_inspect_ctrl, dev_close_tool, dev_close_window, dev_display, dev_get_preferences, dev_get_system, dev_get_window, dev_inspect_ctrl, dev_map_par, dev_map_prog, dev_map_var, dev_open_dialog, dev_open_file_dialog, dev_open_tool, dev_open_window, dev_set_color, dev_set_colored, dev_set_draw, dev_set_line_width, dev_set_lut, dev_set_paint, dev_set_part, dev_set_preferences, dev_set_shape, dev_set_tool_geometry, dev_set_window, dev_set_window_extents, dev_show_tool, dev_unmap_par, dev_unmap_prog, dev_unmap_var, dev_update_pc, dev_update_time, dev_update_var, dev_update_window
Execute Halcon operators and programs within AppSpace.
Type conversion
When executing Halcon procedures or operators, AppSpace input parameters are converted to their corresponding Halcon types. Similarly, Halcon output parameters are converted to Appspace types. The following conversions are supported:
-
String: Halcon control parameter Tuple of type
H_TYPE_STRING -
Floats: Halcon control parameter Tuple of type
H_TYPE_REAL -
Integers: Halcon control parameter Tuple of type
H_TYPE_INT -
Vectors of strings, floats and integers: Halcon control parameter Tuple of their respective type
-
Image: Halcon iconic parameter of type
Image -
Shape and Shape.Composite: Halcon iconic parameter of type
XLD -
Image.PixelRegion: Halcon iconic parameter of type
Region -
PointCloud: Halcon control parameter Tuple referring to an
ObjectModel3D -
Mesh: Halcon control parameters referring to an
ObjectModel3Dwith additional attributestrianglesand possiblypoint_normal_x,point_normal_yandpoint_normal_z
Features
-
A Halcon handle can be reused to load multiple procedures during its lifetime.
-
Input parameters that do not change between executions only need to be set once. That is, there is no need to call
Halcon.setInteger(proc, 'YourParam', 10)prior each call toHalcon.execute(proc)if that parameter does not change. -
Converting single-channel images as input for a Halcon procedure uses a shallow copy. Multi-channel images (RGB) require a deep copy.
|
The scripting engine does not support Halcons protected procedures feature. Please use the read protection property for the application from AppStudio instead. |
A first example:
The following sample loads the Halcon operator sobel_amp, processes the input image and returns the result Image edgeAmplitude:
local input = Image.create(128, 128, "UINT8")
-- create a handle for executing a Halcon procedure
local proc = Halcon.create()
-- load procedure and assign input parmeters
proc:loadProcedure(">sobel_amp")
proc:setImage("Image", input)
proc:setString("FilterType", "sum_abs")
proc:setInteger("Size", 3)
-- execute and obtain result image from output object "EdgeAmplitude"
local result = proc:execute()
local edgeAmplitude = result:getImage("EdgeAmplitude")
Accessing Files and Directories:
The Halcon scripting interface provides placeholders in order to enable Halcon scripts to access the applications resources, private and public folders. If available on the device, also storage mounted by usb, sdcard or ram disk is supported. To this end, the following set of placeholders are available to be used in Halcon procedures:
-
APPDATA_RESOURCESaccess the appsresources/folder -
APPDATA_PRIVATEaccess the appsprivate/folder -
APPDATA_PUBLICaccess the sharedpublic/folder -
APPDATA_SDCARDaccess the shared sdcard storage -
APPDATA_USBaccess the shared usb storage -
APPDATA_RAMaccess the shared volatile memory
These placeholders can be used within Halcon procedures to read and write data. E.g. the following syntax can be used to open an OCR classifier from resources/Classifier.omc of the app:
read_ocr_class_mlp(APPDATA_RESOURCES + 'Classifier.omc', OCRModel)
Please note that these keywords must be used only within the corresponding operator scope. The following is not valid and will yield an error when loading a procedure:
Path := APPDATA_RESOURCES + 'Classifier.omc'
read_ocr_class_mlp(Path, OCRModel)
This syntax is required for all read and write operators in Halcon. The scripting interface restricts the usage of such operators to use one of these placeholders to access any data. Otherwise, the corresponding procedure will not validate during loadProcedure().
Restriction:
The following list of operators performing a read operation can use all placeholders:
caltab_points, create_text_model_reader, disp_caltab, file_exists, find_caltab, find_marks_and_pose, get_prep_info_class_gmm, get_prep_info_class_mlp, get_prep_info_class_svm, get_prep_info_ocr_class_mlp, get_prep_info_ocr_class_svm, import_lexicon, list_files, read_aop_knowledge, read_bar_code_model, read_calib_data, read_cam_par, read_camera_setup_model, read_class_box, read_class_gmm, read_class_knn, read_class_mlp, read_class_svm, read_class_train_data, read_component_model, read_contour_xld_arc_info, read_contour_xld_dxf, read_data_code_2d_model, read_deformable_model, read_deformable_surface_model, read_descriptor_model, read_distance_transform_xld, read_fft_optimization_data, read_funct_1d, read_gray_se, read_image, read_kalman, read_matrix, read_measure, read_metrology_model, read_ncc_model, read_object, read_object_model_3d, read_object_model_3d_dxf, read_ocr, read_ocr_class_cnn, read_ocr_class_knn, read_ocr_class_mlp, read_ocr_class_svm, read_ocr_trainf, read_ocr_trainf_names, read_ocr_trainf_names_protected, read_ocr_trainf_select, read_ocv, read_polygon_xld_arc_info, read_polygon_xld_dxf, read_pose, read_region, read_sample_identifier, read_samples_class_gmm, read_samples_class_mlp, read_samples_class_svm, read_sampset, read_sequence, read_shape_model, read_shape_model_3d, read_sheet_of_light_model, read_surface_model, read_template, read_texture_inspection_model, read_training_components, read_tuple, read_variation_model, read_world_file, select_feature_set_trainf_knn, select_feature_set_trainf_mlp, select_feature_set_trainf_mlp_protected, select_feature_set_trainf_svm, select_feature_set_trainf_svm_protected, set_calib_data_calib_object, sim_caltab, trainf_ocr_class_box, trainf_ocr_class_knn, trainf_ocr_class_mlp, trainf_ocr_class_mlp_protected, trainf_ocr_class_svm, trainf_ocr_class_svm_protected, update_kalman
The following list of operators performing a write operation can use all placeholders except APPDATA_RESOURCES and can thus not access the applications resources/ folder:
delete_file, gen_caltab, open_file, store_par_knowledge, write_aop_knowledge, write_bar_code_model, write_calib_data, write_cam_par, write_camera_setup_model, write_class_box, write_class_gmm, write_class_knn, write_class_mlp, write_class_svm, write_class_train_data, write_component_model, write_contour_xld_arc_info, write_contour_xld_dxf, write_data_code_2d_model, write_deformable_model, write_deformable_surface_model, write_descriptor_model, write_distance_transform_xld, write_fft_optimization_data, write_funct_1d, write_image, write_lut, write_matrix, write_measure, write_metrology_model, write_ncc_model, write_object, write_object_model_3d, write_ocr, write_ocr_class_knn, write_ocr_class_mlp, write_ocr_class_svm, write_ocr_trainf, write_ocr_trainf_image, write_ocv, write_polygon_xld_arc_info, write_polygon_xld_dxf, write_pose, write_region, write_sample_identifier, write_samples_class_gmm, write_samples_class_mlp, write_samples_class_svm, write_shape_model, write_shape_model_3d, write_sheet_of_light_model, write_surface_model, write_template, write_texture_inspection_model, write_training_components, write_tuple, write_variation_model
The following list of operators are not supported and using them within a procedure will yield an error during load time of the procedure:
close_framegrabber, close_io_channel, close_io_device, close_serial, close_socket, control_io_channel, control_io_device, control_io_interface, copy_file, get_current_dir, gnuplot_close, gnuplot_open_file, gnuplot_open_pipe, gnuplot_plot_ctrl, gnuplot_plot_funct_1d, gnuplot_plot_image, import, make_dir, open_compute_device, open_framegrabber, open_io_channel, open_io_device, open_serial, open_socket_accept, open_socket_connect, open_textwindow, protect_ocr_trainf, read_char, read_io_channel, read_serial, read_string, receive_data, receive_image, receive_region, receive_serialized_item, receive_tuple, receive_xld, release_all_compute_devices, release_compute_device, remove_dir, send_data, send_image, send_region, send_serialized_item, send_tuple, send_xld, set_io_channel_param, set_io_device_param, socket_accept_connect, system_call, test_access, write_io_channel, write_serial, write_string
The following list of operators are allowed but they are executed as no-op:
dev_clear_obj, dev_clear_window, dev_close_inspect_ctrl, dev_close_tool, dev_close_window, dev_display, dev_get_preferences, dev_get_system, dev_get_window, dev_inspect_ctrl, dev_map_par, dev_map_prog, dev_map_var, dev_open_dialog, dev_open_file_dialog, dev_open_tool, dev_open_window, dev_set_color, dev_set_colored, dev_set_draw, dev_set_line_width, dev_set_lut, dev_set_paint, dev_set_part, dev_set_preferences, dev_set_shape, dev_set_tool_geometry, dev_set_window, dev_set_window_extents, dev_show_tool, dev_unmap_par, dev_unmap_prog, dev_unmap_var, dev_update_pc, dev_update_time, dev_update_var, dev_update_window
Overview
create(), execute(), getVersion(), loadProcedure(), setComposite(), setCompositeArray(), setContour(), setContourArray(), setDouble(), setDoubleArray(), setIconicParameter(), setImage(), setImageArray(), setInteger(), setIntegerArray(), setMesh(), setPointCloud(), setRegion(), setRegionArray(), setString(), setStringArray()
Functions
create()
Creates a new Halcon handle to load and execute procedures.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle |
local halconHdl = Halcon.create()
execute()
Execute the Halcon loaded Halcon procedure and obtain a handle to the result.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon result object or nil if the execution failed with an error. Inspect the error log for further information. |
local result = Halcon.execute(halconHdl)
getVersion()
Query the version of the Halcon runtime.
| Name | Type | Description |
|---|---|---|
version |
STRING |
The version of the Halcon runtime. Can be nil if Halcon is not licensed. |
local version = Halcon.getVersion()
loadProcedure()
Load a Halcon procedure. Can be used to load an internal operator or custom procedures from an .hdvp files. Use the syntax local success = Halcon.loadProcedure(halconHdl, "resources/MyHalconProcedure.hdvp") local success = Halcon.loadProcedure(halconHdl, ">sobel_amp") Procedures can call other custom procedures given that all procedures are loaded in the correct order. That is, load the callee first than caller: func1 = Halcon.create() func1:loadProcedure("resources/func1.hdvp") — if func1 calls func2 then loading will fail here with an error because func2 is not known func2 = Halcon.create() func2:loadProcedure("resources/func2.hdvp") — func2 can call func1 because func1 is now known The supplementary setup and teardown functions can be used to initialize and clear handle based objects within Halcon. This can be used to e.g. to setup a shape model or a code reader and handle the corresponding clear opearator gracefully. This meachanism allows to handle the initialization and destruction of such models separated from the processing. As an example, the setup function could execute the following lines of code: global def tuple DataCodeHandle create_data_code_2d_model ('QR Code', [], [], DataCodeHandle) The corresponding teardown function handles the destruction: global tuple DataCodeHandle clear_data_code_2d_model (DataCodeHandle) The DataCodeHandle is available for processing.
The following syntax can be used to load a Halcon procedure from an .hdvp file or an internal operator:
local success = Halcon.loadProcedure(halconHdl, "resources/MyHalconProcedure.hdvp")
local success = Halcon.loadProcedure(halconHdl, ">sobel_amp")
Procedures can call other custom procedures given that all procedures are loaded in the correct order. That is, load the callee first than caller:
func1 = Halcon.create()
func1:loadProcedure("resources/func1.hdvp") -- if func1 calls func2 then loading will fail here with an error because func2 is not known
func2 = Halcon.create()
func2:loadProcedure("resources/func2.hdvp") -- func2 can call func1 because func1 is now known
The supplementary setup and teardown functions can be used to initialize and clear handle based objects within Halcon. This can be used to e.g. to setup a shape model or a code reader and handle the corresponding clear operation gracefully. This allows to handle the initialization and destruction of such model handles outside of the processing.
As an example, a setup function could execute the following lines of code to create a QR code model:
global def tuple DataCodeHandle
create_data_code_2d_model ('QR Code', [], [], DataCodeHandle)
The corresponding teardown function handles the destruction:
global tuple DataCodeHandle
clear_data_code_2d_model (DataCodeHandle)
The DataCodeHandle is available for processing.
|
Loading of Halcon program files (.hdev) is not supported. |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle |
procedureName |
STRING |
The name of the external procedure files (.hdvp) or internal Halcon procedure prefixed by the '>' character. |
setupProcedureName |
STRING |
Halcon procedure to initialize global variables. This procedure will be executed once at the end of this call. The setup procedure must take no argument an can not return a value. Internal operators are not allowed. |
teardownProcedureName |
STRING |
Halcon procedure to clear global variables. This procedure will be executed once when the handle is either destroyed or a new procedure is loaded. The teardown procedure must take no argument an can not return a value. Internal operators are not allowed. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if the procedure could be loaded and - if supplied - the setup executed successfully. |
local success = Halcon.loadProcedure(halconHdl, "resources/MyHalconProcedure.hdvp")
setComposite()
Set an iconic XLD input parameter for the Halcon procedure. The Shape.Composite object will be converted to an XLD object.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle |
name |
STRING |
The name of the iconic input variable to assign. |
value |
OBJECT Shape.Composite |
The value of the iconic XLD input parameter to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name. |
local success = Halcon.setComposite(halconHdl, "CompositeVariableName", composite)
setCompositeArray()
Set an iconic input parameter for the Halcon procedure of type XLD array object. The Shape.Composite object will be converted to an XLD object.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle |
name |
STRING |
The name of the iconic input variable to assign. |
value |
OBJECT Shape.Composite |
The value of the iconic XLD input parameter to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name. |
local success = Halcon.setCompositeArray(halconHdl, "CompoundArrayVariableName", {composite1, composite2})
setContour()
Set an iconic XLD input parameter for the Halcon procedure. All shape types will be converted to an XLD object. Conversion for the Line shape is not supported.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle |
name |
STRING |
The name of the iconic input variable to assign. |
value |
OBJECT Shape |
The value of the iconic XLD input parameter to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name. |
local success = Halcon.setContour(halconHdl, "ContourVariableName", contour)
setContourArray()
Set an iconic input parameter for the Halcon procedure of type XLD array object. All shape types will be converted to an XLD object. Conversion for the Line shape is not supported.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the iconic input variable to assign. |
value |
OBJECT Shape |
The value of the iconic XLDs input parameter to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name. |
local success = Halcon.setContourArray(halconHdl, "ContourArrayVariableName", {contour1, contour2})
setDouble()
Set a control input parameter for the Halcon procedure of type double
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the control input variable to assign. |
value |
FLOAT |
The value of the control input variable to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name. |
local success = Halcon.setDouble(halconHdl, "DoubleVariableName", 3.14)
setDoubleArray()
Set a control input parameter for the Halcon procedure of type double array
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the control input variable to assign. |
value |
FLOAT |
The value of the control input variable to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name. |
local success = Halcon.setDoubleArray(halconHdl, "DoubleArrayVariableName", {2.718, math.pi})
setIconicParameter()
Set an iconic input parameter for the Halcon procedure. Use setImage, setRegion and setContour and their Array variants for type-save versions
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the iconic input variable to assign. |
value |
OBJECT [API:DataFormat:] |
The value of the iconic input variable to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name. |
local success = Halcon.setIconicParameter(halconHdl, "IconicVariableName", Iconic)
setImage()
Set an iconic input parameter for the Halcon procedure of type Image object. Conversion is supported for the following pixel types: uint8, int8, unit16, int16, int32, real
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the iconic image input parameter to assign. |
value |
OBJECT Image |
The value of the iconic Image input parameter to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name. |
local success = Halcon.setImage(halconHdl, "ImageVariableName", image)
setImageArray()
Set an iconic input parameter for the Halcon procedure of type Image array object. Conversion is supported for the following pixel types: uint8, int8, unit16, int16, int32, real
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the iconic input variable to assign. |
value |
OBJECT Image |
The value of the iconic Images input parameter to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name. |
local success = Halcon.setImageArray(halconHdl, "ImageArrayVariableName", {image1, image2})
setInteger()
Set a control input parameter for the Halcon procedure of type integer
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the control input variable to assign. |
value |
INT |
The value of the control input variable to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name. |
local success = Halcon.setInteger(halconHdl, "IntegerVariableName", 42)
setIntegerArray()
Set a control input parameter for the Halcon procedure of type integer array
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the control input variable to assign. |
value |
INT |
The value of the control input variable to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name. |
local success = Halcon.setIntegerArray(halconHdl, "IntegerArrayVariableName", {1, 2, 3})
setMesh()
Set a ObjectModel3D as input to a procedure. The Mesh is converted into a ObjectModel3D and the corresponding handle is passed to the procedure as control input parameter with the corresponding name. Important: The ObjectModel3D has to be cleared by calling to the operator 'clear_object_model_3d' eventually.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle |
name |
STRING |
The name of the iconic input variable to assign. |
value |
OBJECT Mesh |
The Mesh to convert to an ObjectModel3D |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the object could not be converted or the procedure has no control input variable with the corresponding name. |
local success = Halcon.setMesh(halconHdl, "ObjectModel3D", cloud)
setPointCloud()
Set a ObjectModel3D as input to a procedure. The PointCloud is converted into a ObjectModel3D and the corresponding handle is passed to the procedure as control input parameter with the corresponding name. Important: The ObjectModel3D has to be cleared by calling to the operator 'clear_object_model_3d' eventually.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle |
name |
STRING |
The name of the iconic input variable to assign. |
value |
OBJECT PointCloud |
The PointCloud to convert to an ObjectModel3D |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the object could not be converted or the procedure has no control input variable with the corresponding name. |
local success = Halcon.setPointCloud(halconHdl, "ObjectModel3D", cloud)
setRegion()
Set an iconic Region input parameter for the Halcon procedure. The Image.PixelRegion will be converted to a Region object.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle |
name |
STRING |
TThe name of the iconic input variable to assign. |
value |
OBJECT Image.PixelRegion |
The value of the iconic region input parameter to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name. |
local success = Halcon.setRegion(halconHdl, "RegionVariableName", region)
setRegionArray()
Set an iconic input parameter for the Halcon procedure of type Region array object. The Image.PixelRegion will be converted to a Region object.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the iconic input variable to assign. |
value |
OBJECT Image.PixelRegion |
The value of the iconic Regions input parameter to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the iconic could not be converted or the procedure has no iconic input variable with the corresponding name. |
local success = Halcon.setRegionArray(halconHdl, "RegionArrayVariableName", {region1, region2})
setString()
Set a control input parameter for the Halcon procedure of type string
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the control input variable to assign. |
value |
STRING |
The value of the control input variable to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name. |
local success = Halcon.setString(halconHdl, "StringVariableName", "foo")
setStringArray()
Set a control input parameter for the Halcon procedure of type string array
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The Halcon handle. |
name |
STRING |
The name of the control input variable to assign. |
value |
STRING |
The value of the control input variable to assign. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true unless the control input parameter could not be converted or the procedure has no control input parameter with the corresponding name. |
local success = Halcon.setStringArray(halconHdl, "StringArrayVariableName", {"foo", "bar"})
Halcon.Result
Obtain results from executed Halcon procedure calls
Overview
Functions
getContour()
Get a contour output parameter from the Halcon procedure result
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable of the Halcon procedure |
| Name | Type | Description |
|---|---|---|
contour |
OBJECT Shape.Composite |
The return parameter or nil on error |
local contour = Halcon.Result.getContour(halconHdl, "ContourVariableName")
getContourArray()
Get a contour array output parameter from the Halcon procedure result
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable of the Halcon procedure |
| Name | Type | Description |
|---|---|---|
contours |
OBJECT Shape.Composite |
The return parameter or nil on error |
local contours = Halcon.Result.getContourArray(halconHdl, "ContourArrayVariableName")
getDouble()
Get a control output parameter from the Halcon procedure result of type float
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable in the Halcon procedure |
| Name | Type | Description |
|---|---|---|
value |
FLOAT |
The float value of output variable or nil on error |
local value = Halcon.Result.getDouble(halconHdl, "VariableName")
getDoubleArray()
Get a control output parameter from the Halcon procedure result of type double array
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the control output variable in the Halcon procedure |
| Name | Type | Description |
|---|---|---|
value |
FLOAT |
The float array of output variable or nil on error |
local value = Halcon.Result.getDoubleArray(halconHdl, "VariableName")
getIconicParameter()
Get an iconic output parameter from the Halcon procedure result
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable of the Halcon procedure |
| Name | Type | Description |
|---|---|---|
object |
OBJECT [API:DataFormat:] |
The return parameter or nil on error |
local image = Halcon.Result.getIconicParameter(halconHdl, "IconicVariableName")
getImage()
Get an image output parameter from the Halcon procedure result
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable of the Halcon procedure |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The return parameter or nil on error |
local image = Halcon.Result.getImage(halconHdl, "ImageVariableName")
getImageArray()
Get an image array output parameter from the Halcon procedure result
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable of the Halcon procedure |
| Name | Type | Description |
|---|---|---|
images |
OBJECT Image |
The return parameter or nil on error |
local images = Halcon.Result.getImageArray(halconHdl, "ImageArrayVariableName")
getInteger()
Get a control output parameter from the Halcon procedure result of type integer
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable in the Halcon procedure |
| Name | Type | Description |
|---|---|---|
value |
INT |
The integer value of output variable or nil on error |
local value = Halcon.Result.getInteger(halconHdl, "VariableName")
getIntegerArray()
Get a control output parameter from the Halcon procedure result of type integer array
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the control output variable in the Halcon procedure |
| Name | Type | Description |
|---|---|---|
value |
INT |
The integer array of output variable or nil on error |
local value = Halcon.Result.getIntegerArray(halconHdl, "VariableName")
getMesh()
Get a ObjectModel3D output parameter from the Halcon procedure result. The ObjectModel3D is converted into a Mesh. Unless 'doNotFreeObjectModel3D' is set, the corresponding ObjectModel3D is deleted by calling the operator 'clear_object_model_3d' internally. Important: When a procedure returns an ObjectModel3D as an output parameter, calling this function is mandatory in order to avoid a memory leak.
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable of the Halcon procedure |
doNotFreeObjectModel3D |
BOOL |
The name of the output variable of the Halcon procedure |
| Name | Type | Description |
|---|---|---|
mesh |
OBJECT Mesh |
The return parameter or nil on error |
local mesh = Halcon.Result.getMesh(halconHdl, "ObjectModel3D")
getPointCloud()
Get a ObjectModel3D output parameter from the Halcon procedure result. The ObjectModel3D is converted into a PointCloud. Unless 'doNotFreeObjectModel3D' is set, the corresponding ObjectModel3D is deleted by calling the operator 'clear_object_model_3d' internally. Important: When a procedure returns an ObjectModel3D as an output parameter, calling this function is mandatory in order to avoid a memory leak.
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable of the Halcon procedure |
doNotFreeObjectModel3D |
BOOL |
The name of the output variable of the Halcon procedure |
| Name | Type | Description |
|---|---|---|
cloud |
OBJECT PointCloud |
The point cloud of n points or nil on error |
normals |
OBJECT Matrix |
The normals represented as n x 4 matrix if the object model has normal information. The first three columns represent the normal dircetion in x, y, and z. The fourth column is a curvature term that si set to 0. Nil otherwise. |
local cloud = Halcon.Result.getPointCloud(halconHdl, "ObjectModel3D")
getRegion()
Get a region output parameter from the Halcon procedure result
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable of the Halcon procedure |
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
The return parameter or nil on error |
local region = Halcon.Result.getRegion(halconHdl, "RegionVariableName")
getRegionArray()
Get a region array output parameter from the Halcon procedure result
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable of the Halcon procedure |
| Name | Type | Description |
|---|---|---|
regions |
OBJECT Image.PixelRegion |
The return parameter or nil on error |
local regions = Halcon.Result.getRegionArray(halconHdl, "RegionArrayVariableName")
getString()
Get a control output parameter from the Halcon procedure result of type string
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the output variable in the Halcon procedure |
| Name | Type | Description |
|---|---|---|
value |
STRING |
The string value of output variable or nil on error |
local value = Halcon.Result.getString(halconHdl, "VariableName")
getStringArray()
Get a control output parameter for the Halcon procedure result of type string array
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT Halcon.Result |
The Halcon result handle |
name |
STRING |
The name of the control output variable in the Halcon procedure |
| Name | Type | Description |
|---|---|---|
value |
STRING |
The string array of output variable or nil on error |
local value = Halcon.Result.getStringArray(halconHdl, "VariableName")
Hash
Namespace for different kinds of hash algorithms. All algorithms have two usage possibilities depending on the users needs: - calculate()-function: For single calculation of the input data and return of the hash value - Create a handle: For multiple incremental calculations useful if the input data is fragmented There are two result options: - Default is as bytes in a binary buffer - Alternative is as hex-ASCII values in a string
Hash.CRC32
CRC32 hashing algorithm. To possibilities for usage: - Use the calculate()-function to calculate a single hash - Create a handle: For multiple incremental calculations useful if the input data is fragmented There are two result options: - Default is as bytes in a binary buffer - Alternative is as hex-ASCII values in a string
Overview
Functions
calculate()
Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as byte buffer.
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The input data to calculate the hash |
| Name | Type | Description |
|---|---|---|
hash |
BINARY |
The hash result as byte buffer with size of 4 bytes |
hash = Hash.CRC32.calculate(buf)
calculateHex()
Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as hex-ASCII string.
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The input data to calculate the hash |
| Name | Type | Description |
|---|---|---|
hash |
STRING |
The hash result as hex-ASCII string with size of 8 characters |
hash = Hash.CRC32.calculateHex(buf)
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
handle = Hash.CRC32.create()
getHashValue()
Returns the current hash value as byte buffer. The current hash value is based on the data which was added before with calls to the update()-function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
hash |
BINARY |
The hash result as byte buffer with size of 4 bytes |
Hash.CRC32.getHashValue(buf)
getHashValueHex()
Returns the current hash value as hex-ASCII string. The current hash value is based on the data which was added before with calls to the update()-function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
hashString |
STRING |
The hash result as hex-ASCII string with size of 8 characters |
Hash.CRC32.getHashValueHex(buf)
update()
Update the hash object with the specified data. This function can be called multiple times e.g. if not all data is currently available.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
data |
BINARY |
The input data to calculate the hash |
Hash.MD5
MD5 hashing algorithm. To possibilities for usage: - Use the calculate()-function to calculate a single hash - Create a handle: For multiple incremental calculations useful if the input data is fragmented There are two result options: - Default is as bytes in a binary buffer - Alternative is as hex-ASCII values in a string
Overview
Functions
calculate()
Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as byte buffer.
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The input data to calculate the hash |
| Name | Type | Description |
|---|---|---|
hash |
BINARY |
The hash result as byte buffer with size of 16 bytes |
hash = Hash.MD5.calculate(buf)
calculateHex()
Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as hex-ASCII string.
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The input data to calculate the hash |
| Name | Type | Description |
|---|---|---|
hash |
STRING |
The hash result as hex-ASCII string with size of 32 characters |
hash = Hash.MD5.calculateHex(buf)
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
handle = Hash.MD5.create()
getHashValue()
Returns the current hash value as byte buffer. The current hash value is based on the data which was added before with calls to the update()-function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
hash |
BINARY |
The hash result as byte buffer with size of 16 bytes |
Hash.MD5.getHashValue(buf)
getHashValueHex()
Returns the current hash value as hex-ASCII string. The current hash value is based on the data which was added before with calls to the update()-function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
hashString |
STRING |
The hash result as hex-ASCII string with size of 32 characters |
Hash.MD5.getHashValueHex(buf)
update()
Update the hash object with the specified data. This function can be called multiple times e.g. if not all data is currently available.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
data |
BINARY |
The input data to calculate the hash |
Hash.SHA256
SHA256 hashing algorithm. To possibilities for usage: - Use the calculate()-function to calculate a single hash - Create a handle: For multiple incremental calculations useful if the input data is fragmented There are two result options: - Default is as bytes in a binary buffer - Alternative is as hex-ASCII values in a string
Overview
Functions
calculate()
Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as byte buffer.
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The input data to calculate the hash |
| Name | Type | Description |
|---|---|---|
hash |
BINARY |
The hash result as byte buffer with size of 32 bytes |
hash = Hash.SHA256.calculate(buf)
calculateHex()
Convenience function to do a single hash calculation in one function call. The hash result is returned directly here as hex-ASCII string.
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The input data to calculate the hash |
| Name | Type | Description |
|---|---|---|
hash |
STRING |
The hash result as hex-ASCII string with size of 64 characters |
hash = Hash.SHA256.calculateHex(buf)
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
handle = Hash.SHA256.create()
getHashValue()
Returns the current hash value as byte buffer. The current hash value is based on the data which was added before with calls to the update()-function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
hash |
BINARY |
The hash result as byte buffer with size of 32 bytes |
Hash.SHA256.getHashValue(buf)
getHashValueHex()
Returns the current hash value as hex-ASCII string. The current hash value is based on the data which was added before with calls to the update()-function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
hashString |
STRING |
The hash result as hex-ASCII string with size of 64 characters |
Hash.SHA256.getHashValueHex(buf)
update()
Update the hash object with the specified data. This function can be called multiple times e.g. if not all data is currently available.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
data |
BINARY |
The input data to calculate the hash |
Image
Object for images, height maps, distance maps and similar data sampled on a regularly spaced grid. The samples are referred to as pixels whose values can be represented using different types such as unsigned integers (e.g., uint8, uint16), signed integers (e.g., int8, int16), floats (e.g., float32, float64) or RGB24 (3 times uint8 for the red, green and blue channels). The locations of the regular grid points can be described in physical world units, typically in millimeters, using the so-called image world coordinate system. The image world coordinate system is left-handed and aligned with the image axes, with the x-axis pointing from left to right, and a y-axis pointing from top towards bottom, and the origin at the upper left pixel. As the coordinate system is left-handed, positive rotations are specified clock-wise. The image coordinate system is specified as a world origin coordinate of the upper left pixel (pixel center) and a pixel size (e.g., in millimeters) in the x- and y-dimensions. The image world origin and pixel size are provided as meta data in the Image object. For regular gray scale/reflectance images captured by a 2D camera, the default world origin and pixel size are (0,0) and (1,1) respectively, so that the pixel index and image world coordinate system are the same. For height map and depth maps for which pixel values represent ranges in the physical world, there is also a scale factor available from raw pixel value to a physical world unit (typically millimeter). For compact notation, this scaling factor is referred to as pixel size in the z-dimension, and there is also a corresponding world origin in the z-dimension. The Image object meta data also has a 'missing data' flag that indicates if the value 0 is a reserved number representing the absence of measurement rather than the actual numeric value 0. Algorithms will then try to ignore missing data pixels in calculations instead of using the actual value 0. The missing data flag is only supported for unsigned integer types (uint8, uint16, etc) and not for signed types (int16, float32, etc.)
Overview
abs(), absInplace(), add(), addConstant(), addConstantInplace(), addInplace(), addNoise(), addNoiseInplace(), addPlane(), addPlaneInplace(), adjustOriginZ(), adjustOriginZInplace(), bilateral(), binarize(), binarizeAdaptive(), binarizeCompare(), binarizePlane(), bitShift(), bitShiftInplace(), blur(), canny(), clamp(), clampInplace(), clampPlane(), clampPlaneInplace(), clone(), concatenate(), create(), createFromMemory(), crop(), cropRectify(), cropRegion(), difference(), distanceTransform(), divide(), divideInplace(), drawPixelRegion(), drawPixelRegionInplace(), drawPoint(), drawPointCloud(), drawPointCloudInplace(), drawPointInplace(), drawProfile(), drawProfileInplace(), drawShape(), drawShapeInplace(), drawText(), drawTextInplace(), equalizeHistogram(), extractColumnProfile(), extractProfile(), extractRowProfile(), fillRegion(), fillRegionInplace(), findLineSegments(), findLocalExtrema(), gauss(), getFlatRegion(), getFlatness(), getHeight(), getHistogram(), getMax(), getMean(), getMedian(), getMin(), getMinMax(), getMissingDataFlag(), getMissingDataImage(), getMissingDataRegion(), getOrigin(), getPercentiles(), getPixel(), getPixelSize(), getSize(), getSum(), getType(), getValidDataRegion(), getWidth(), getWorldZ(), growRegion(), houghTransformCircle(), houghTransformExtremaToCircles(), houghTransformExtremaToLines(), houghTransformLine(), inpaint(), invert(), invertInplace(), isEqual(), isWithinBounds(), laplace(), load(), max(), maxInplace(), median(), min(), minInplace(), mirror(), missingDataReduce(), missingDataSetAll(), missingDataSetAllInplace(), missingDataSetSurface(), missingDataSetSurfaceInplace(), morphology(), mosaic(), multiply(), multiplyAddConstant(), multiplyAddConstantInplace(), multiplyConstant(), multiplyConstantInplace(), multiplyInplace(), normalize(), pad(), pow(), powInplace(), renderPlane(), renderPlaneInplace(), renderText(), renderTextInplace(), replace(), replaceInplace(), resize(), resizeScale(), rotate(), rotate90(), save(), setAll(), setColumn(), setColumnProfile(), setMissingDataFlag(), setOrigin(), setOriginZ(), setPixel(), setPixelSize(), setPixelSizeZ(), setRow(), setRowProfile(), sobel(), sobelMagnitude(), splitRGB(), subtract(), subtractInplace(), subtractPlane(), subtractPlaneInplace(), subtractProfile(), subtractProfileInplace(), thin(), threshold(), thresholdCompare(), thresholdPlane(), toGray(), toHSV(), toLab(), toMatrix(), toPixelCoordinate(), toPixelZ(), toPointCloud(), toRGB(), toSquarePixels(), toString(), toType(), toWorldCoordinate(), toWorldZ(), transform(), transformInto(), transformInto3D(), warpSector()
Functions
abs()
Computes the absolute value of each pixel. Image world coordinate system handling: The operation is not implemented for images with z-origin different from 0.0. The image metadata from the input image is copied to the output image. Missing data handling: There is no special handling of missing data as the value 0 remains 0 after the operation.
arithmetic, magnitude, absolute
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The absolute value image. |
result = Image.abs(image)
absInplace()
Inplace version of the Image.abs function that modifies the input image. See base function for full documentation.
arithmetic, magnitude, absolute
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The source image. This image is overwritten with the result image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
A reference to the result image. |
Image.absInplace(image)
add()
Adds two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.
arithmetic, sum
| Name | Type | Description |
|---|---|---|
image1 |
CONST_OBJECT Image |
The first source image. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The sum image. |
result = Image.add(image1, image2)
addConstant()
Adds a constant value to all pixels in the image. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, the constant is interpreted in image world coordinate units, e.g., millimeters, and is rescaled to a raw pixel value using the z-pixelsize and z-origin of the image. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
arithmetic, level, plus, offset
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
constant |
FLOAT |
The constant interpreted in image world units (z-origin and z-pixelsize taken into account). |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The sum image. |
result = Image.addConstant(image, constant)
addConstantInplace()
Inplace version of Image.addConstant function which modifies the input image. See base function for full documentation.
arithmetic, level, plus, offset
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The source image. |
constant |
FLOAT |
The constant interpreted in image world units (z-origin and z-pixelsize taken into account). |
| Name | Type | Description |
|---|---|---|
resultReference |
OBJECT Image |
Reference to the sum image. |
Image.addConstantInplace(image, constant)
addInplace()
Inplace version of the Image.add function which modifies the first input image to contain the sum of the input images. See base function for full documentation.
arithmetic, sum
| Name | Type | Description |
|---|---|---|
image1 |
OBJECT Image |
The first source image. This image is overwritten with the sum. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.addInplace(image1, image2)
addNoise()
Adds a uniform noise value in the range [a,b] to all pixels in the image. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a heightmap, distance or range image, the noise interval parameters [a,b] are interpreted in image world coordinate units, e.g., millimeters, and is rescaled to a raw pixel value using the z-pixelsize and z-origin of the image. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
random, uniform, white
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
a |
FLOAT |
Lower interval limit interpreted in image world units (z-origin and z-pixelsize taken into account). |
b |
FLOAT |
Upper interval limit interpreted in image world units (z-origin and z-pixelsize taken into account). |
randSeed |
INT |
Random seed, optional. Default value is 0. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The result image. |
result = Image.addNoise(image, 10, 100, 0)
addNoiseInplace()
Inplace version of the Image.addNoise function that modifies the input image. See base function for full documentation.
random, uniform, white
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The source image. This image is overwritten with the result image. |
a |
FLOAT |
Lower interval limit interpreted in image world units (z-origin and z-pixelsize taken into account). |
b |
FLOAT |
Upper interval limit interpreted in image world units (z-origin and z-pixelsize taken into account). |
randSeed |
INT |
Random seed, optional. Default value is 0. |
| Name | Type | Description |
|---|---|---|
resultReference |
OBJECT Image |
A reference to the result image. |
Image.addNoiseInplace(image, 10, 100, 0)
addPlane()
Adds the value of a plane function (Shape3D) to every pixel in an image. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. Image world coordinate system handling: The plane is interpreted in world space and added to the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
gradient, ramp
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. |
plane |
CONST_OBJECT Shape3D |
The plane to add, must be a Shape3D plane. |
region |
CONST_OBJECT Image.PixelRegion |
Region of the image where the plane should be added, default is the full image. An empty region or nil are interpreted as the full image. |
| Name | Type | Description |
|---|---|---|
resultImage |
OBJECT Image |
The image with the added plane. Nil if an error occurred. |
resultImage = Image.addPlane(image, plane, region)
addPlaneInplace()
Inplace version of the Image.addPlane function which modifies the input image by adding the value of a given plane. See base function for full documentation.
gradient, ramp
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image. This image is overwritten with the result image. |
plane |
CONST_OBJECT Shape3D |
The plane to add, must be a Shape3D plane. |
region |
CONST_OBJECT Image.PixelRegion |
Region of the image where the plane should be added, default is the full image. An empty region or nil are interpreted as the full image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.addPlaneInplace(image, plane, region)
adjustOriginZ()
Adjusts the image z-origin to the given value in world coordinates, changing the raw pixel values such that the represented world coordinate values stays the same. Adjusting the z-origin to -10.0 will allow unsigned types to represent world-coordinate values from -10.0 and larger. Pixel values outside the range of the image type will be clamped. To set a new origin without changing the raw pixel values, offsetting the world coordinate values, see Image.setOriginZ. Image world coordinate system handling: The operation keeps pixel values in the world coordinate system constant, unless underflow or overflow occurs. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The input image image. |
newOriginZ |
FLOAT |
New origin in z-direction for image. |
| Name | Type | Description |
|---|---|---|
resultImage |
OBJECT Image |
The image with the adjusted origin. Nil if an error occurred. |
resultImage = Image.adjustOriginZ(image, newOriginZ)
adjustOriginZInplace()
Inplace version of the Image.adjustOriginZ function that modifies the input image. See base function for full documentation.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The input image image. |
newOriginZ |
FLOAT |
New origin in z-direction for image. |
| Name | Type | Description |
|---|---|---|
resultImage |
OBJECT Image |
The image with the adjusted origin. Nil if an error occurred. |
resultImage = Image.adjustOriginZInplace(image, newOriginZ)
bilateral()
Applies a bilateral filter to an image. The bilateral filter is similar to a Gauss filter but it also adaptively modifies the filter kernel to avoid smoothing over image boundaries. Image world coordinate system handling: The kernel size in the range/z-dimension is interpreted in world scale, e.g., millimeters, it is internally divided by the z-pixelsize to get raw pixel value thresholds. The output image inherits the image world coordinates. Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.
edge preserving, filter, gauss, sigma, denoise
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, float32 and rgb24. |
kernelSizeSpatialPix |
INT |
Size of the kernel in pixels, must be positive and odd. |
kernelSizeRange |
FLOAT |
Range of intensity values that affect the filtering, must be positive. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
| Name | Type | Description |
|---|---|---|
filteredImage |
OBJECT Image |
Filtered image |
filteredImage = Image.bilateral(image, kernelSizeSpatialPix, kernelSizeRange)
binarize()
Applies a threshold interval (lowerThreshold, upperThreshold) to the image to create a binary image. It is possible to binarize only a specified region. This function produces an image output, to directly produce a PixelRegion output use the threshold() function instead. Image world coordinate system handling: The input threshold values are interpreted in image world coordinates, i.e., they are converted to raw pixel thresholds within the function using the z-origin and z-pixelsize. As the output image is binary the output z-origin is set to 0 and the z-pixelsize to 1. The output image inherits the image world coordinates in the xy-dimensions. Missing data handling: Missing data pixels are set to background, i.e., to 0 in the output image. The output image has its missing data flag turned off regardless of the flag of the input image.
Image.binarizeAdaptive, Image.binarizeCompare, Image.binarizePlane, Image.thresholdCompare, Image.threshold
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, uint32, uint64, int8, int16, int32, int64, float32 and float64. |
lowerThreshold |
FLOAT |
Lower threshold for the binarization in image world coordinates, i.e., the z-pixel size and origin are used so that the threshold is interpreted in millimeters in case the image is a height map/distance/range image. |
upperThreshold |
FLOAT |
Upper threshold for the binarization in world coordinates. Optional, defaults to max value of the pixel type. |
outputValue |
INT |
Value assigned to the pixels within the threshold interval, uint8 range. Optional, default value is 255. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest to consider when binarizing, values outside are set to zero. |
| Name | Type | Description |
|---|---|---|
binarizedImage |
OBJECT Image |
Binarized image of pixel type uint8. |
thresholdImage = Image.binarize(image, lowerThreshold, upperThreshold, outputValue, region)
binarizeAdaptive()
Applies an adaptive filter to the image to create a binary image. A pixel is set in the binary output image if the value is significantly larger than the average value in a surrounding region of specified size. The threshold is set as a delta value how much larger the pixel value must be in world coordinates, i.e, the delta threshold value is scaled internally with the pixel size in the z-dimension. In its base form, bright objects on dark background are found. There is a parameter to instead find dark objects on a bright background.
Image.binarizeCompare, Image.binarizePlane, Image.threshold, Image.thresholdCompare, Image.binarize
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image, currently only uint8 format is supported. |
deltaThresholdWorld |
FLOAT |
Threshold value, all pixels with a value higher than the mean in the surrounding region plus this threshold is set to outputValue |
kernelSizePix |
INT |
Size of the kernel in number of pixels, must be odd and greater than one. |
findBright |
BOOL |
Set to true to find bright objects on dark background. Set to false to find dark objects on a bright background. Optional, default is true. |
outputValue |
INT |
Value assigned to the pixels within the threshold interval, uint8 range. Optional, default value is 255. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
| Name | Type | Description |
|---|---|---|
binarizedImage |
OBJECT Image |
Adaptively binarized image. |
filteredImage = Image.binarizeAdaptive(image, deltaThresholdWorld, kernelSizePix, findBright, outputValue, region)
binarizeCompare()
Binarizes an image by pixelwise comparison with a reference image. All pixels with a value greater than or equal to the corresponding reference image value are included in the binary output image. An optional margin (positive or negative) may be provided, adjusting the reference image values prior to the comparison. A larger positive margin results in fewer included pixels. The optional flag findBright may be set to false, returning the region where the image is lower/darker than the reference image. A region of interest can be provided, limiting the processing to that region. The images must be of the same pixel type and be of equal size. This function gives an Image object as output, to get a PixelRegion output use thresholdCompare instead. Image world coordinate system handling: To allow for an efficient comparison, the z-pixelsizes of the input images must be equal but the z-offsets may differ. The margin parameter is interpreted in image world coordinates, e.g., as a millimeter margin if the input is a range image. The output image inherits x,y-origin and x,y-pixelsizes but the z-origin is set to 0 and z-pixelsize to 1. Missing data handling: Missing data pixels are excluded from the output.
adaptive, background, foreground, segmentation
Image.binarize, Image.binarizeAdaptive, Image.binarizePlane, Image.thresholdCompare, Image.thresholdPlane, Image.threshold
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image to binarize. |
referenceImage |
CONST_OBJECT Image |
Reference image to compare the input image with. |
marginWorld |
FLOAT |
Optional offset of the reference image. Default value is 0. |
findBright |
BOOL |
Optional flag indicating if pixels brighter/higher or darker/lower than the reference image should be included. Default is true, returning brighter pixels. |
outputValue |
FLOAT |
Optional value for pixels in the output image mask, default 255. |
regionOfInterest |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. The default region is the entire image. |
| Name | Type | Description |
|---|---|---|
maskImage |
OBJECT Image |
Image containing all pixels passing the comparison operation. |
maskImage = Image.binarizeCompare(image, referenceImage, marginWorld, findBright, outputValue, regionOfInterest)
binarizePlane()
Applies a threshold interval (lowerThreshold, upperThreshold) relative to the given plane to create a binary image from a height map. The threshold values accounts for world coordinates (pixel size and origin in the z-dimension) if applicable. It is possible to binarize only a specified region. The thresholds may both be negative or positive, allowing selecting values strictly below or above the reference. This function produces an image output, to directly produce a PixelRegion output use the thresholdPlane function instead. Image world coordinate system handling: The plane is interpreted in world space which is compared with the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the output image mask has the same pixel size and origin in x,y as the input image. Along the value axis z, the pixel size and origin are reset to unit and zero respectively. Missing data handling: No pixels marked as missing are included in the output mask. The missing data flag of the output mask image is cleared.
adaptive, background, foreground, segmentation, binarize
Image.binarize, Image.binarizeAdaptive, Image.binarizeCompare, Image.threshold, Image.thresholdPlane, Image.binarize
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, uint32, int8, int16, int32, float32 and float64. |
lowerThreshold |
FLOAT |
Lower threshold for the binarization in image world coordinates, i.e., the z-pixel size and origin are used so that the threshold is interpreted in millimeters in case the image is a height map/distance/range image. |
upperThreshold |
FLOAT |
Upper threshold for the binarization in world coordinates. |
plane |
CONST_OBJECT Shape3D |
The plane to which the lower and upper thresholds are related. The shape should be a plane. |
outputValue |
INT |
Value assigned to the pixels within the threshold interval, uint8 range. Optional, default value is 255. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest to consider when binarizing, values outside are set to zero. |
| Name | Type | Description |
|---|---|---|
binaryImage |
OBJECT Image |
Binarized image of pixel type uint8. |
binaryImage = Image.binarizePlane(image, lowerThreshold, upperThreshold, plane, outputValue, region)
bitShift()
Bit shifts all pixel values in an image of unsigned integer type. This is a fast way of multiplying or dividing (integer division) image values with powers of two. Negative shift length is used for division. Note that there are no overflow or underflow checks for this operation! The operation is performed correctly both for raw pixel values and world pixel values. There is a slight difference when shifting using positive values compared to a real multiplication when going out of bounds. The bitshift operation simply drops the most significant bit. For an image of uint8 and a pixel value of 255 this would mean that shifting once with a positive value would shift in one zero and thus producing a lower value than before (254). Ex. 1111 1111 << 0 (uint8 255) 1111 1110 << 0 (uint8 254) 1111 1100 (uint8 252) As can be seen the behavior is not the ideal once the limit of the data type is reached. To avoid this problem use a sufficiently large image data type, or to get the a saturating behavior, see Image.multiplyConstant. Image world coordinate system handling: If the image has a non-zero z-origin, the z-origin of the returned image is adjusted in order to keep the operation valid both for raw- and world pixels. All other origin values and all pixel sizes are respected and copied to the returned image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, additional pixels may be marked as missing.
arithmetic, divide, scale, multiply
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
shifts |
INT |
The shift length in number of bits, each positive shift corresponds to multiplying with two. Each negative shift corresponds to division with two. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The bit-shifted image. |
result = Image.bitShift(image, shifts)
bitShiftInplace()
Inplace version of Image.bitShift function which modifies the input image. See base function for full documentation.
arithmetic, divide, multiply
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The source image. This image is overwritten with the result image. |
shifts |
INT |
The shift length in number of bits, each positive shift corresponds to multiplying with two. Each negative shift corresponds to division with two. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.bitShiftInplace(image, shifts)
blur()
Blurs an image using a constant normalized box filter kernel. Image world coordinate system handling: The box filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.
box, boxcar, convolve, denoise, filter, smooth
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, int16, float32 and float64. |
kernelSizePix |
INT |
Size of the kernel, must be positive. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
fillMissingData |
BOOL |
Optional flag to also fill in missing data pixels when smoothing images containing missing data. Default is false. |
| Name | Type | Description |
|---|---|---|
smoothImage |
OBJECT Image |
Output image blurred by the blur filter. Same type as input image. |
smoothImage = Image.blur(image, kernelSizePix)
canny()
Applies Canny edge detection to find edges in an image. The Canny edge detection works with a dual threshold procedure: first strong edges are found using a high threshold value. A second lower threshold also detects weaker edges in the image, and the weaker edges that are connected with the stronger edges are kept in the output edge image. A non-maximum suppression operation is also applied to obtain 1-pixel wide edge responses. The Canny function currently only operates on uint8 images. Image world coordinate system handling: The input thresholds are interpreted in world scale, e.g., millimeters, they are internally divided by the z-pixelsize to get raw pixel value thresholds. The output image inherits the image world coordinates in the x,y-dimensions, but the z-pixelsize is set to 1 and the z-origin to 0. Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.
derivative, gradient, edge
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Currently only uint8 pixel type is supported. |
thresholdHigh |
FLOAT |
First/high threshold to find strong edges, for example a value of 100. |
thresholdLow |
FLOAT |
Second/low threshold for finding weaker edges connected with the strong edges, for example a value of 50. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
| Name | Type | Description |
|---|---|---|
cannyImage |
OBJECT Image |
Output image. |
cannyImage = Image.canny(image, thresholdHigh, thresholdLow)
clamp()
Clamps the pixel values to an interval [maxValue, minValue]. An optional region may be provided, limiting the processing to only that region. Pixels outside the region are left in an undefined state. Image world coordinate system handling: The [maxValue, minValue] parameters are interpreted as expressed in image world coordinate units, i.e., the clamp limits are scaled internally from world (millimeter) units to raw pixel values using the origin and pixelsize in the z-dimension. The image metadata from the input image is copied to the output image. Missing data handling: A missing data pixel in the input image results in a missing data pixel in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image. Setting the optional fillMissingData flag, missing data pixels will be set to the minimum clamp value. If this flag is set, the output image will have its missing data flag cleared.
arithmetic, limit, clip
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
minValueWorld |
FLOAT |
The minimum value to clamp to interpreted in image world units (z-origin and z-pixelsize taken into account). |
maxValueWorld |
FLOAT |
The maximum value to clamp to in image world units (z-origin and z-pixelsize taken into account). |
region |
CONST_OBJECT Image.PixelRegion |
Optional region to process. Default is the entire image. |
fillMissingData |
BOOL |
Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The clamped image. |
result = Image.clamp(image, minValue, maxValue, region, fillMissingData)
clampInplace()
Inplace version of the Image.clamp function that modifies the input image. See base function for full documentation.
arithmetic, limit, clip
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The source image. This image is overwritten with the result image. |
minValueWorld |
FLOAT |
The minimum value to clamp to interpreted in image world units (z-origin and z-pixelsize taken into account). |
maxValueWorld |
FLOAT |
The maximum value to clamp to in image world units (z-origin and z-pixelsize taken into account). |
region |
CONST_OBJECT Image.PixelRegion |
Optional region to process. Default is the entire image. |
fillMissingData |
BOOL |
Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.clampInplace(image, minValue, maxValue, region, fillMissingData)
clampPlane()
Clamps image pixel values to a plane from below, i.e., values are raised to the plane. In case of overflow, the value is instead clamped to the maximal representable value. A partial region of operation may be selected, reducing the processing time. All pixels outside the region are left in an undefined state. Image world coordinate system handling: The plane is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: By default, a missing data pixel in the input image generates a missing data pixel in the output image. If the fillMissingData flag is set to true, all pixels with missing data will be set to the plane value and the missing data flag of the output image will be cleared. In that case, the full range of raw pixel values may be used.
limit, clip
Image.addPlane, Image.clampPlaneInplace, Image.renderPlane, Image.subtractPlane, Image.clamp
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to clamp. |
plane |
CONST_OBJECT Shape3D |
The plane to clamp to, must be a Shape3D plane. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region where clamping should be performed, default is the full image. An empty region or nil are interpreted as the full image. |
fillMissingData |
BOOL |
Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false. |
| Name | Type | Description |
|---|---|---|
clampedImage |
OBJECT Image |
The clamped image. Nil if an error occurred. |
clampedImage = Image.clampPlane(image, plane, region, fillMissingData)
clampPlaneInplace()
Inplace version of the Image.clampPlane function that modifies the input image. See base function for full documentation.
limit, clip
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to clamp. This image is overwritten with the result image. |
plane |
CONST_OBJECT Shape3D |
The plane to clamp to, must be a Shape3D plane. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region where clamping should be performed, default is the full image. An empty region or nil are interpreted as the full image. |
fillMissingData |
BOOL |
Optional flag to also fill in missing data pixels when clamping images containing missing data. Default is false. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.clampPlaneInplace(image, plane, region, fillMissingData)
clone()
Returns a duplicated instance of the input image. New memory to copy all pixel data is allocated.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to clone. |
| Name | Type | Description |
|---|---|---|
clone |
OBJECT Image |
The new cloned image object. |
local imageClone = Image.clone(image)
concatenate()
Concatenates two images. Image world coordinate system handling: The image world coordinate system is used to update the output image origin. The new origin depends on how image2 is placed in relation to image1 (direction), the different possibilities are: - ABOVE (Oxout, Oyout, Ozout) = (Oximage1, Oyimage1-image2Height*image2PixelSizeY, Ozimage1) - BELOW (Oxout, Oyout, Ozout) = (Oximage1, Oyimage1, Ozimage1) - RIGHT (Oxout, Oyout, Ozout) = (Oximage1, Oyimage1, Ozimage1) - LEFT (Oxout, Oyout, Ozout) = (Oximage1-image2Width*image2PixelSizeX, Oyimage1, Ozimage1) Both input images must have the same pixel size, inherited by the output image. Missing data handling: The output image missing data flag is inherited from image1.
union, join
| Name | Type | Description |
|---|---|---|
image1 |
CONST_OBJECT Image |
The first image. |
image2 |
CONST_OBJECT Image |
The second image. |
direction |
The direction of the concatenation, i.e. where to place image2 in relation to image1, default is to the right of image1. |
| Name | Type | Description |
|---|---|---|
imageOut |
OBJECT Image |
The concatenated image. |
local imageOut = Image.concatenate(image1, image2, 1)
create()
Creates a new image of a certain size and pixel type.
| Name | Type | Description |
|---|---|---|
width |
INT |
The image width in pixels. |
height |
INT |
The image height in pixels. |
type |
ENUM ImageType |
The pixel type, for example UINT8, INT16, FLOAT64. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The new image object. |
local image = Image.create(800,600,"UINT8")
createFromMemory()
Creates a new image of a certain size and pixel type by copying the data of a binary buffer.
| Name | Type | Description |
|---|---|---|
buffer |
BINARY |
The buffer containing the raw image data. |
width |
INT |
The image width in pixels. |
height |
INT |
The image height in pixels. |
type |
ENUM ImageType |
The pixel type, for example UINT8, INT16, FLOAT64. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The new image object. |
local image = Image.createFromMemory(buffer,800,600,"UINT8")
crop()
Crops a subpart of an image, specified in pixel coordinates. A cropped image is a clone of the source data.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to crop. |
x |
INT |
The x position of the top-left corner of the cropped image in the source image. |
y |
INT |
The y position of the top-left corner of the cropped image in the source image. |
width |
INT |
The width of the cropped image. |
height |
INT |
The height of the cropped image. |
| Name | Type | Description |
|---|---|---|
imageCropped |
OBJECT Image |
Cropped image or nil on error. |
local imageCropped = Image.crop(fullImage, 10, 10, 100, 100)
cropRectify()
Crops the region defined by a rotated rectangle or a closed polyline, and also rotates/transforms the cropped image patch to become axis-aligned using a linear interpolation operation. The size of the output image is determined automatically to obtain approximately the same pixel resolution as the input image has. If the crop region extends outside the input image borders, the corresponding pixels in the output image get the value 0. For a Shape Rectangle type region input, the function crops and rotates the content within the rectangle to a new image. The rotation of the input rectangle is reversed so that the output is defined by a zero-degree-rotated rectangle with the same width and height as the input rectangle. For a Shape Polyline type region input, it is a requirement that the polyline has exactly 4 points and that it encloses a convex region, e.g., it must not self-intersect. The function then crops the defined region and applies a homography transform to transform the content into an axis-aligned bounding box. The order of the four points in the polyline is relevant. The following mapping from points in the polyline to corners in the output image patch is made: - 1st point maps to upper left corner - 2nd point maps to upper right corner - 3rd point maps to lower right corner - 4th point maps to lower left corner. The transform from the input shape (Rectangle or Polyline region) and the output image is also provided. With this transform it is possible to map features, e.g., points, from the input image to the cropped image, and vice versa with the inverse of the transform. The transform is of rigid type when possible and of homography type otherwise. Image world coordinate system handling: New x,y pixel sizes are calculated, based on the input shape and input image. For example, a 90 degree rotated rectangle as a shape would just swap the pixel sizes in x and y in the output image. For non-rectangular shapes the average pixel sizes in the x,y-dimensions are used. Missing-data handling: For images with the missing data flag set, missing data aware sampling will be used and the output image will also set its missing data flag. Values being sampled outside of the image will get the value 0.
align, box, homography, rectangle, rotate, transform, warp, cut
Image.Calibration.Correction, Image.cropRegion, Image.rotate, Image.transformInto, Image.warpSector, Image.crop
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to crop. |
shape |
CONST_OBJECT Shape |
Input Shape defining the region to crop. Must either be of Rectangle type or of Polyline type with 4 points enclosing a convex region with an area greater than 1. |
| Name | Type | Description |
|---|---|---|
imageCropped |
OBJECT Image |
Cropped and rectified image. |
transform |
OBJECT Transform |
Transformation from the input shape to the new image. The transform is of rigid type for a Rectangle shape input and of homography type otherwise. |
imageCropped, transform = Image.cropRectify(image, shape)
cropRegion()
Crops the region defined by the bounding box of an input pixelregion. Optionally, padding around the bounding box can also be specified in order to extend it. The pixelregion bounding box is defined by the limits of its non-empty pixels. The output cropped pixelregion is a copy of the region corresponding to the padded pixelregion bounding box (crop region). The cropped image contains a copy of the values inside the crop region. The image size is equal to the size of the crop region, the pixel size is the same as the input image and the image origin value is equal to the top left corner of the crop region. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the origin changes to the value of the top left corner of the crop region. Missing-data handling: The missing data information is kept from the input image.
bounding box, cut
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to crop |
region |
CONST_OBJECT Image.PixelRegion |
Input region to crop around. The crop region is defined by the bounding box of the region. |
paddingPix |
INT |
How much padding around the bounding box of the region that should be added in pixels. Optional, default value is 0. |
| Name | Type | Description |
|---|---|---|
imageCropped |
OBJECT Image |
The cropped image. Returns nil if the input padded pixelregion bounding box is not contained inside the input image. |
regionCropped |
OBJECT Image.PixelRegion |
The region corresponding to the input pixelregion bounding box plus padding if used. Returns nil if the input padded pixelregion bounding box is not contained inside the input image. |
imageCropped, regionCropped = Image.cropRegion(image, region)
difference()
Computes the pixel-wise difference between two images, using a configurable difference operator. The images must be of equal size and pixel type, and have the same pixel size and origin in the z-dimension. Difference operators: ABS: Absolute difference, |image1 - image2|. SQUARE: Squared difference, (image1 - image2)^2. Return image type: The return image type for all integer image types is unsigned. For SQUARE difference operator, a larger integer type is returned, e.g. UINT16 if the input is INT8. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.
arithmetic, minus, subtract
| Name | Type | Description |
|---|---|---|
image1 |
CONST_OBJECT Image |
The first source image. |
image2 |
CONST_OBJECT Image |
The second source image. |
differenceMode |
ENUM DifferenceMode |
The type of difference operator to be used. Default is ABS. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The difference image. |
result = Image.difference(image1, image2, "SQUARE")
distanceTransform()
Applies the distance transform operation on the input image. Each pixel in the output image gives the approximate Euclidean distance to the closest background pixel (value = 0) in the input image. Typically the input image is a binarized image with 0:s representing the background and some other value (e.g. 1 or 255) representing the foreground. Currently only the uint8 pixel type is supported. Image world coordinate system handling: The image world coordinate system is not considered in this function. The distances in the output image are in pixel units, i.e., not scaled with the world pixel sizes in x and y. The output image inherits the image world coordinate system of the input image in the x,y dimensions, but the z-origin is set to 0 and the z-pixelsize is set to 1 regardless of the input values. Missing data handling: The function does not consider the missing data flag of the input image. The missing data flag of the output will be set to false, i.e., no missing data.
chamfer, manhattan, skeleton, euclidian
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image, expected to be binary. Only uint8 type supported. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
| Name | Type | Description |
|---|---|---|
distanceImage |
OBJECT Image |
Distance image with approximate Euclidean distance values, float32 type. |
distanceImage = Image.distanceTransform(image)
divide()
Divides two images pixelwise. The images must be of equal size and pixel type. A division-by-zero leads to a 0 in the output image. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate value. The second image is treated as a unit-less modifier and it must therefore have a standard image world coordinate system with pixel sizes all equal to 1 and origins equal to 0. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. Note that it is possible to obtain 0 as result of the division and that such pixels then will be considered as missing data in subsequent processing steps.
arithmetic, ratio
| Name | Type | Description |
|---|---|---|
image1 |
CONST_OBJECT Image |
The first source image. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The quotient image. |
result = Image.divide(image1, image2)
divideInplace()
Inplace version of the Image.divide function which modifies the first input image to contain the ratio of the input images. See base function for full documentation.
arithmetic, ratio
| Name | Type | Description |
|---|---|---|
image1 |
OBJECT Image |
The first source image. This image is overwritten with the image ratio. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.divideInplace(image1, image2)
drawPixelRegion()
Render one or several PixelRegions into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. The View.PixelRegionDecoration object is used to set the color of the rendered regions. Image world coordinate system handling: The input PixelRegion is interpreted in raw pixel coordinates, the image world coordinate system is not considered. Missing data handling: This function does not use the missing data flag.
display, fill, overlay, paint, plot, print, render, rasterize
Image.PixelRegion.toImage, Image.applyColormap, Image.drawPoint, Image.drawShape, Image.drawText, Image.toRGB, View.addPixelRegion
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to render the region(s) into. Supported image types are UINT8 and RGB. |
regions |
CONST_OBJECT Image.PixelRegion |
The region(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT View.PixelRegionDecoration |
A decorator that describes how the region(s) are to be rendered. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
RGB image with rendered overlay. |
image = Image.drawPixelRegion(image, regions, decoration)
drawPixelRegionInplace()
Inplace version of the Image.drawPixelRegion function which modifies the input image. See base function for full documentation.
display, fill, overlay, paint, plot, print, render, rasterize
Image.PixelRegion.toImage, Image.applyColormap, Image.applyColormap, Image.drawPixelRegion, Image.drawPoint, Image.drawShape, Image.drawText, Image.toRGB, View.addPixelRegion
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to render the region(s) into. Supported image type is RGB. |
shapes |
CONST_OBJECT Image.PixelRegion |
The region(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT View.PixelRegionDecoration |
A decorator that describes how the region(s) are to be rendered. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
RGB image with rendered overlay. Reference to input image. |
image = Image.drawPixelRegionInplace(image, regions, decoration)
drawPoint()
Render the position of one or several points into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. to RGB. The View.ShapeDecoration object is used to set graphical properties. The following parameters in the ShapeDecoration object are supported: - The LineColor property is used to set the color of the points. - The PointType property is used to render points as circles or crosses. - The PointSize property is used to set the size of the rendered points. Image world coordinate system handling: The points coordinates are interpreted as world coordinates. That is, the coordinate system of the image is used to place the points properly. Missing data handling: This function does not use the missing data flag.
display, overlay, paint, plot, print, render, rasterize
Image.applyColormap, Image.drawPixelRegion, Image.drawPointInplace, Image.drawShape, Image.drawText, Image.toRGB, Shape.toImage, View.addShape
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to render the point(s) into. Supported image types are UINT8 and RGB. |
points |
CONST_OBJECT Point |
The points (2D) that are to be rendered in the image. |
decoration |
CONST_OBJECT View.ShapeDecoration |
A decorator that describes how the point(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
RGB image with rendered overlay. |
image = Image.drawPoint(image, points, decoration)
drawPointCloud()
Render one or several pointclouds into an image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. The x- and y- coordinates of each point in the pointcloud are used to place each point into the image world coordinate system. Points are rendered using the information in the PointCloudDecoration object. The following properties in the PointCloudDecoration object are supported: - The ZRange or IntensityRange parameters: If there is a ZRange set, the colors of the rendered points will be based on the z-values. Otherwise the intensity component of each point is used, either using the IntensityRange parameter or using the default range for intensity colors which is 0 to 1. - The PointSize parameter. Image world coordinate system handling: The world coordinate system of the image if respected and each point in the pointcloud is drawn at the corresponding image position. Missing data handling: This function does not use the missing data flag.
display, fill, overlay, paint, plot, print, render, rasterize
Image.applyColormap, Image.drawPixelRegion, Image.drawPoint, Image.drawPointCloudInplace, Image.drawProfile, Image.drawShape, Image.drawText, Image.toRGB
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to render the point clouds(s) into. Supported image types are UINT8 and RGB. |
pointcloud |
CONST_OBJECT PointCloud |
The point clouds(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT View.PointCloudDecoration |
A decorator that describes how the point clouds(s) are to be rendered. Not all properties of the PointCloudDecoration object are supported, see the main function description. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
RGB image with rendered overlay. |
image = Image.drawPointCloud(image, pointcloud, decoration)
drawPointCloudInplace()
Inplace version of the Image.drawPointCloud function which modifies the input image. See base function for full documentation.
display, fill, overlay, paint, plot, print, render, rasterize
Image.applyColormap, Image.drawPixelRegion, Image.drawPoint, Image.drawProfile, Image.drawShape, Image.drawText, Image.toRGB, Image.drawPointCloud
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to render the point clouds(s) into. Supported image type is RGB. |
pointcloud |
CONST_OBJECT PointCloud |
The point clouds(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT View.PointCloudDecoration |
A decorator that describes how the point clouds(s) are to be rendered. Not all properties of the PointCloudDecoration object are supported, see the main function description. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
RGB image with rendered overlay. |
image = Image.drawPointCloudInplace(image, pointcloud, decoration)
drawPointInplace()
Inplace version of the Image.drawPoint function which modifies the input image. See base function for full documentation.
display, overlay, paint, plot, print, render, rasterize
Image.applyColormap, Image.drawPixelRegion, Image.drawPoint, Image.drawShape, Image.drawText, Image.toRGB, Shape.toImage, View.addShape
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to render the point(s) into. Supported image type is RGB. |
points |
CONST_OBJECT Point |
The points (2D) that are to be rendered in the image. |
decoration |
CONST_OBJECT View.ShapeDecoration |
A decorator that describes how the point(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
RGB image with rendered overlay. Reference to input image. |
image = Image.drawPointInplace(image, points, decoration)
drawProfile()
Render one or several profiles into an image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. For profiles with 1D coordinates the coordinate vector is mapped to the x-axis of the image and the value vector to the y-axis. Each sample in the profile is then drawn in the image world coordinate system. For profiles with 2D coordinates the value vector is discarded and the profile is drawn on its coordinates in the image world coordinate system. Note: This function differs from the View.addProfile function in that it does not provide the full graph plotting functionality as a dedicated graph viewer does, e.g., coordinate axes, background grids etc. are not rendered with the drawProfile function. Color and line width properties are controlled using the View.GraphDecoration object. The two properties used for this are the GraphColor and DrawSize properties in the GraphDecoration object. No other properties in the GraphDecoration are currently supported. Image world coordinate system handling: The world coordinate system of the image if respected and each profile is drawn at the corresponding image position. Missing data handling: This function does not use the missing data flag.
display, fill, overlay, paint, plot, print, render, rasterize
Image.applyColormap, Image.drawPixelRegion, Image.drawPoint, Image.drawProfileInplace, Image.drawShape, Image.drawText, Image.toRGB
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to render the profile(s) into. Supported image types are UINT8 and RGB. |
profiles |
CONST_OBJECT Profile |
The profile(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT View.GraphDecoration |
A decorator that describes how the profiles(s) are to be rendered. The DrawSize (line width) and GraphColor (line color) properties are supported. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
RGB image with rendered overlay. |
image = Image.drawProfile(image, profiles, decoration)
drawProfileInplace()
Inplace version of the Image.drawProfile function which modifies the input image. See base function for full documentation.
display, fill, overlay, paint, plot, print, render, rasterize
Image.applyColormap, Image.drawPixelRegion, Image.drawPoint, Image.drawProfile, Image.drawShape, Image.drawText, Image.toRGB
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to render the profile(s) into. Supported image type is RGB. |
profiles |
CONST_OBJECT Profile |
The profile(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT View.GraphDecoration |
A decorator that describes how the profiles(s) are to be rendered. The DrawSize (line width) and GraphColor (line color) properties are supported. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
RGB image with rendered overlay. |
image = Image.drawProfileInplace(image, profiles, decoration)
drawShape()
Render the position of one or several shapes into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. The View.ShapeDecoration object is used to set graphical properties. The following parameters in the ShapeDecoration object are supported: - The LineColor property is used to set the border color of the rendered shape. - The FillColor property is used to set the fill color of the rendered shape. - The LineWidth property is used to set width of the border. Image world coordinate system handling: The shape coordinates are interpreted as world coordinates. That is, the coordinate system of the image is used to place the shapes properly. Missing data handling: This function does not use the missing data flag.
display, overlay, paint, plot, print, render, rasterize
Image.applyColormap, Image.drawPixelRegion, Image.drawPoint, Image.drawShapeInplace, Image.drawText, Image.toRGB, Shape.toImage, View.addShape
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to render the shape(s) into. Supported image types are UINT8 and RGB. |
shapes |
CONST_OBJECT Shape |
The shape(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT View.ShapeDecoration |
A decorator that describes how the shape(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
RGB image with rendered overlay. |
image = Image.drawShape(image, shapes, decoration)
drawShapeInplace()
Inplace version of the Image.drawShape function which modifies the input image. See base function for full documentation.
display, overlay, paint, plot, print, render, rasterize
Image.applyColormap, Image.drawPixelRegion, Image.drawPoint, Image.drawShape, Image.drawText, Image.toRGB, Shape.toImage, View.addShape
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to render the shape(s) into. Supported image type is RGB. |
shapes |
CONST_OBJECT Shape |
The shape(s) that are to be rendered in the image. |
decoration |
CONST_OBJECT View.ShapeDecoration |
A decorator that describes how the shape(s) are to be rendered. Not all properties of the ShapeDecoration object are supported, see the main function description. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
RGB image with rendered overlay. Reference to input image. |
image = Image.drawShapeInplace(image, shapes, decoration)
drawText()
Renders text into an image by modifying the pixel values. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. Not all features of the TextDecoration input are supported. Features that are supported are the following: * Position - Fully supported. * Color - Does not support opacity. * Size - Approximately matching to viewer settings. * Font family - SANSSERIF and SERIF are supported, MONOSPACE is unsupported. * Font weight - Fully supported, but does not exactly match viewer behavior. * Horizontal alignment - Full support apart from JUSTIFY, but does not exactly match viewer behavior. * Vertical alignment - Fully supported, but does not exactly match viewer behavior Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The font position will adjust to the image coordinate system, but the font size will only scale with the y-resolution. Missing data handling: This function does not use the missing data flag.
characters, display, draw, letters, overlay, paint, plot, print, render, write, rasterize
Image.drawPixelRegion, Image.drawPoint, Image.drawShape, Image.drawTextInplace, Image.renderText, Image.renderTextInplace, View.addText
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to render the text into. This image is overwritten with the rendered text. Supported image types are UINT8 and RGB. |
text |
STRING |
The characters that cannot be rendered using the specified font are replaced by question marks. |
decoration |
CONST_OBJECT View.TextDecoration |
A decorator that describes how the text should be rendered. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
RGB image with rendered overlay. |
result = Image.drawText(image, text, decoration)
drawTextInplace()
Inplace version of the Image.drawText function that modifies the input image. See base function for full documentation.
characters, display, draw, letters, overlay, paint, plot, print, render, write, rasterize
Image.drawPixelRegion, Image.drawPoint, Image.drawShape, Image.drawText, Image.renderText, Image.renderTextInplace, View.addText
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to render the text into. This image is overwritten with the rendered text. Supported image type is RGB. |
text |
STRING |
The characters that cannot be rendered using the specified font are replaced by question marks. |
decoration |
CONST_OBJECT View.TextDecoration |
A decorator that describes how the region(s) should be rendered. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
RGB image with rendered overlay. Reference to input image. |
result = Image.drawTextInplace(image, text, decoration)
equalizeHistogram()
Applies histogram equalization to an image.
contrast, intensity, normalize, stretch, scale
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Only uint8 type supported. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
| Name | Type | Description |
|---|---|---|
equalizedImage |
OBJECT Image |
Equalized image |
equalizedImage = Image.equalizeHistogram(image)
extractColumnProfile()
Extracts one profile from an image column. The number of samples in the profile is always the same as the number of pixels between the start and end row (end position is included). Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The image column to extract from is provided as a zero-based integer pixel coordinate. The coordinate representation in the generated Profile object will be of implicit 2D or 1D type. Default is 2D, where the start point is the (x,y) world coordinates of the first extracted pixel in the image column and the delta vector the spacing between pixels in the y-dimension. Optionally, 1D coordinates can be returned, in which case the sample coordinates are set to the y-coordinates of the sampled pixels. Missing data handling: Valid data flags are enabled in the output profile if and only if the image contains missing data. Points sampled on missing data pixels are marked as invalid.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. All pixel types are supported. |
column |
INT |
The column to extract as a profile. |
startRow |
INT |
The first row index to extract. If no index is given 0 will be used. |
stopRow |
INT |
The last row index extract. If no index is given the image height-1 will be used. |
sampleCoordinates1D |
BOOL |
If set to true, the output profile will have implicit 1D coordinates, keeping only the y-coordinates of the sample points. Default is false, generating implicit 2D sample coordinates. |
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
Sampled profile, or nil if unsuccessful. |
local profile = Image.extractColumnProfile(image, column, startRow, stopRow)
extractProfile()
Samples image values evenly along a contour defined by a 2D Shape object and generates a Profile object. Supported shape types are line segment, arc, circle and polyline. Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The coordinate representation in the generated Profile object will be of implicit type if the contour shape allows it. For example, coordinates along a line segment contour can be represented using the implicit start + delta vector representation. For more complex contours such as a circle, an explicit coordinate representation is used in the Profile object where all the sample points are stored as individual entries. If the contour shape is closed, e.g., a circle, the closed flag in the Profile is also set. Missing data handling: Valid data flags are enabled in the output profile if and only if the image has missing data activated. Points sampled on missing data are marked as invalid. Points sampled outside the image are marked as invalid. In the latter case and if the image does not have missing data activated, the valid flags of the generated profile are set accordingly but are not enabled.
line segment, sample
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. All pixel types are supported. |
shape |
CONST_OBJECT Shape |
The shape to sample along. Supported shapes are line segment, arc, circle and polyline. |
sampleCount |
INT |
The number of samples to take, evenly spaced along the input shape. |
interpolation |
ENUM InterpolationMethod |
Interpolation method, NEAREST or LINEAR. Default is NEAREST. |
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
Generated Profile object, or nil if unsuccessful. |
local profile = Image.extractProfile(image, shape, sampleCount, interpolation)
extractRowProfile()
Extracts one profile from an image row. The number of samples in the profile is always the same as the number of pixels between the start and end column (end position is included). Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The image row to extract from is provided as a zero-based integer pixel coordinate. The coordinate representation in the generated Profile object will be of implicit 2D or 1D type. Default is 2D, where the start point is the (x,y) world coordinates of the first extracted pixel in the image row and the delta vector the spacing between pixels in the x-dimension. Optionally, 1D coordinates can be returned, in which case the sample coordinates are set to the x-coordinates of the sampled pixels. Missing data handling: Valid data flags are enabled in the output profile if and only if the image contains missing data. Points sampled on missing data pixels are marked as invalid.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. All pixel types are supported. |
row |
INT |
The row to extract as a profile, zero-based. |
startColumn |
INT |
The first column index to extract, zero-based. If no index is given 0 will be used. |
stopColumn |
INT |
The last column index extract, zero-based. If no index is given the image width-1 will be used. |
sampleCoordinates1D |
BOOL |
If set to true, the output profile will have implicit 1D coordinates, keeping only the x-coordinates of the sample points. Default is false, generating implicit 2D sample coordinates. |
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
Sampled profile, or nil if unsuccessful. |
local profile = Image.extractRowProfile(image, row, startColumn, stopColumn, sampleCoordinates1D)
fillRegion()
Set all pixels within the given region(s) in the target image to a specific value in world coordinates. The pixels outside the input region keep their original values. A new image with updated values is returned, and the input image is left unchanged. Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. If the value parameter is outside the image value range it will be clamped to the closest valid value. The output image inherits the image world coordinate system of the input image. Missing data handling: The missing data flag is kept in the output image, but the pixels in the fill region will be updated with non missing data.
inpaint, flood
Image.PixelRegion.fillRegion, Image.drawPixelRegion, Image.drawShape, Image.fillRegionInplace, Image.growRegion, Image.inpaint, Image.replace
| Name | Type | Description |
|---|---|---|
inputImage |
CONST_OBJECT Image |
Input image. |
region |
CONST_OBJECT Image.PixelRegion |
The region(s) to fill. |
value |
FLOAT |
World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image. |
| Name | Type | Description |
|---|---|---|
outputImage |
OBJECT Image |
Result image or nil if operation failed. |
outputImage = Image.fillRegion(inputImage, region, value)
fillRegionInplace()
Inplace version of the Image.fillRegion function that modifies the input image. See base function for full documentation.
inpaint, flood
Image.PixelRegion.fillRegionInplace, Image.drawPixelRegion, Image.fillRegion, Image.replace
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image. This image is overwritten with the result image. |
region |
CONST_OBJECT Image.PixelRegion |
The region(s) to fill. |
value |
FLOAT |
World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.fillRegionInplace(image, region, value)
findLineSegments()
Finds line segments in an image. Returns a list of 2D line segments represented as a Shape type. An empty list is returned when no line segments were found during an otherwise successful call. This function is currently limited to uint8 pixel type images. Image world coordinate system handling: The output Shape line segments are expressed using the image world coordinate system in the xy-dimensions. The z-dimension is not used in this function. Missing data handling: This function does not support images with missing data. Fill in missing data before hand, using e.g., missingDataSetAll.
edge, hough
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Support currently limited to uint8 pixel type. |
scale |
FLOAT |
The scale of the image that will be used to find the lines. Accepted values are strictly larger than zero and smaller or equal to one. Optional, default is 0.8. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
mergeLines |
BOOL |
Optional flag to merge line segments that are on the same line. Defaults to false. |
| Name | Type | Description |
|---|---|---|
lineSegments |
OBJECT Shape |
The detected line segments in image world coordinates, or nil on failure. |
lineSegments = Image.findLineSegments(image)
findLocalExtrema()
Finds local extreme points (minima or maxima) in an image. A point is a local maxima if it is larger than all points within a neighborhood of the specified size. An optional contrast threshold level can be defined that sets a required value difference between the local maxima and the smallest value in the neighborhood. For local plateaus, where several pixels have the same value, the top left pixel is reported. An absolute threshold can be specified, if so, point values must exceed the threshold value to be reported. Local minima are detected similarly. Early stopping is used, the neighborhood is only searched until it is clear that the pixel at hand is not an extremal point, starting with the four closest neighbor pixels. The function thus runs faster on smooth images. The absoluteThreshold can also be used to speed up the processing, only considering pixels larger (smaller) than the threshold. The entire neighborhood must fit within the image around extreme points e.g. if neighborhoodSize = 5, no extreme points will be detected closer than three pixels from the image border. Image world coordinate system handling: The thresholds are specified in world values, taking z-origin and pixel size into account. The output pixel region is defined on the pixel grid of the image. Missing data handling: This function does not handle missing data. Remove missing data before calling this function.
maxima, min, minima, max
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, uint32, int8, int16, float32 and float64. |
extremaType |
ENUM ExtremaType |
Which type of extrema to look for. MIN or MAX. |
neighborhoodSize |
INT |
The neighborhood size, width and height in pixels. Must be odd and >= 3. Default is 3. |
contrastThreshold |
FLOAT |
Required height of the peak/valley (world coordinate value difference between the extreme point and surrounding points). Set to zero to disable (default). |
contrastDifferenceMode |
Determines how the difference between the extreme point and the surrounding points is calculated. Default is ONE, at least one point in the neighborhood should differ more than contrastThreshold from the local extremal point. |
|
absoluteThreshold |
FLOAT |
Absolute threshold, extremal points must be above (maxima) or below (minima) this value to be included in the output. By default, this threshold is not used. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
| Name | Type | Description |
|---|---|---|
extremalRegions |
OBJECT Image.PixelRegion |
PixelRegion with local extremal points. |
extremalRegions = Image.findLocalExtrema(image, extremaType, neighborhoodSize, contrastThreshold, contrastDifferenceMode, absoluteThreshold, region)
gauss()
Applies a Gaussian filter to smooth an image. Image world coordinate system handling: The Gaussian filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.
blur, convolve, denoise, filter, smooth
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, int16, float32 and float64. |
kernelSizePix |
INT |
Size of the kernel, must be positive and odd. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
fillMissingData |
BOOL |
Optional flag to also fill in missing data pixels when smoothing images containing missing data. Default is false. |
gaussianFilterType |
ENUM GaussianFilterType |
Optional selection of which algorithm to use for Gaussian smoothing. Default is dependent on the filter size, a Gaussian kernel is used for small filters and an IIR approximation is used for large filters. |
| Name | Type | Description |
|---|---|---|
smoothImage |
OBJECT Image |
Output image smoothed by the Gaussian filter. Same type as input image. |
smoothImage = Image.gauss(image, kernelSizePix)
getFlatRegion()
Find approximately flat regions in an image, typically a heightmap or distance image. The algorithm fits a plane to a local neighborhood around each pixel. If all pixel values / z-values in the neighborhood deviate less than a user-specified threshold from the fitted plane, the central pixel is considered to be in a flat region. There is a fast and slow method for the plane fitting, where the slower method uses all pixels in the neighborhood to estimate the plane and the fast method only uses the border values in the neighborhood. Smoothing the input image first using a blur, gauss or median filter can sometimes be advisable. Image world coordinate system handling: Every position in the output region will have a maximum distance to the fitted plane in world units evaluated on the all pixels under the kernel that is lower than the threshold supplied. Missing data handling: Missing data is accepted, but partly ignored. No pixels that are missing in the input will be part of the output region. For pixels neighboring missing data the missing data positions are allowed to influence the flatness evaluation, possibly breaking the flatness constraint.
planar, planarity, roughness, structure, surface
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. |
threshold |
FLOAT |
Distance tolerance from the locally fitted plane in world units, e.g., millimeters. If all pixels in the neighborhood deviate less than the threshold the central pixel is classified as flat. The Image.getFlatness function can give an indication of possible threshold values. |
neighborhoodSize |
INT |
The size of the neighborhood in pixels. Must be positive and odd. Default value is 13 pixels. |
fast |
BOOL |
Faster central difference estimate (true) or slower least squares fit (false) for the plane fitting. Default is true. |
pixelRegion |
CONST_OBJECT Image.PixelRegion |
Optional pixelregion specifying where in the image to perform the operation. |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
The resulting region of flat pixels. |
outputRegion = Image.getFlatRegion(image, threshold, neighborhoodSize)
getFlatness()
Calculates a flatness measure for each pixel in an image. A pixel with a value close to zero means approximate coplanarity with its neighbors. The algorithm fits a plane to a local neighborhood around each pixel and gives out the maximum deviation from the plane over all pixels in the neighborhood. There is a fast and slow method for the plane fitting, where the slower method uses all pixels in the neighborhood to estimate the plane and the fast method only uses the border values in the neighborhood. Smoothing the input image first using a blur, gauss or median filter can sometimes be advisable. Image world coordinate system handling: Every pixel in the flatness image stores the maximum distance to the fitted plane in world units evaluated on the all pixels under the neighborhood. Missing data handling: Missing data is accepted, but partly ignored. All pixels that are missing data in the input image will get a negative planarity measure (corresponding to 1 z-pixelsize ). For pixels neighboring missing data the missing data positions are allowed to influence the flatness evaluation, possibly inflating the flatness measure.
planar, planarity, roughness, structure, surface
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. |
neighborhoodSize |
INT |
The size of the neighborhood in pixels. Must be positive and odd. Default value is 13 pixels. |
fast |
BOOL |
Faster central difference estimate (true) or slower least squares fit (false). Default is true. |
pixelRegion |
CONST_OBJECT Image.PixelRegion |
Optional pixelregion specifying where in the image to perform the operation. |
| Name | Type | Description |
|---|---|---|
flatness |
OBJECT Image |
A FLOAT32 image with flatness estimates. |
flatness = Image.getFlatness(image, neighborhoodSize)
getHeight()
Returns the height of an image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to get the height of. |
| Name | Type | Description |
|---|---|---|
height |
INT |
Height of the image in pixels. |
local height = Image.getHeight(image)
getHistogram()
Get a histogram of the image values. If the image supports missing data, pixels marked as missing are not included in the histogram. The histogram is computed using world coordinates (z-axis offset and scaling have influence). If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. Pixels with values outside the interval are not counted. See also Image.PixelRegion.getHistogram.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image, specifying values to use in the histogram. |
binCount |
INT |
Number of bins. Uses 32 bins as default. |
minValue |
FLOAT |
Minimum of the value range to cover. Uses an automatic range if omitted. |
maxValue |
FLOAT |
Maximum of the value range to cover. Uses an automatic range if omitted. |
| Name | Type | Description |
|---|---|---|
histogram |
FLOAT |
Histogram, represented as a vector of floats. |
binCenters |
FLOAT |
The center of each histogram bin in the input value range. |
histogram, centers = Image.getHistogram(image, 64)
getMax()
Returns the maximum pixel value in an image. The position of the first maximal value pixel and its uniqueness is also returned. Optionally, a pixel region may be provided. Image world coordinate system handling: The output value is specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are ignored.
rank, statistics, maximum
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region in which to find the min and max, default is the entire image. |
| Name | Type | Description |
|---|---|---|
maxValue |
FLOAT |
The maximum pixel value in world coordinates (millimeters). |
position |
OBJECT Point |
The position of the first maximal value pixel in the image scan order, in world coordinates (millimeters). |
unique |
BOOL |
Boolean indicating if there is only one pixel with the maximal value. |
maxValue = Image.getMax(image)
getMean()
Get the mean pixel value. If a region is provided, the mean is calculated within that region. By default, a reference plane z=0 is used. Another reference plane may be provided, giving the mean difference from that plane. Several regions in a list may be used, in which case one mean value is calculated for each region. When using multiple regions, empty regions are reported as having mean value zero. Image world coordinate system handling: The output mean value is specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are not included.
average, statistics, mean
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image, defines the image from which to get pixel value input. |
region |
CONST_OBJECT Image.PixelRegion |
Input region or regions, defines the region of image in which to calculate the mean, default is the entire image. If several regions are provided, a list of mean values is returned. |
referenceSurface |
CONST_OBJECT Shape3D |
Reference plane, defines the zero level in world coordinates. Default is the plane z=0. |
| Name | Type | Description |
|---|---|---|
mean |
FLOAT |
Mean value or list of mean values. Nil on error |
mean = Image.getMean(image, region, referenceSurface)
getMedian()
Get the median value of the pixels within the region, a special case of Image.PixelRegion.getPercentiles. The median is derived from a histogram and it is approximate. Optionally, a reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. The default surface is the plane z=0.
percentile, statistics
Image.getMax, Image.getMin, Image.getPercentiles, Image.getMean
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image, defines the image from which to get pixel value input. |
region |
CONST_OBJECT Image.PixelRegion |
Input region or regions, defines the region of image in which to calculate the median, default is the entire image. If several regions are provided, a list of median values is returned. |
referenceSurface |
CONST_OBJECT Shape3D |
Zero-reference plane for pixel world coordinate values. Optional, default is the plane z=0. |
| Name | Type | Description |
|---|---|---|
median |
FLOAT |
The approximate median(s). |
median = Image.getMedian(image, region, referenceSurface)
getMin()
Returns the minimum pixel value in an image. The position of the first minimal value pixel and its uniqueness is also returned. Optionally, a pixel region may be provided. Image world coordinate system handling: The output value is specified in image world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are ignored.
rank, statistics, minimum
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region in which to find the min and max, default is the entire image. |
| Name | Type | Description |
|---|---|---|
minValue |
FLOAT |
The minimum pixel value in world coordinates (millimeters). |
position |
OBJECT Point |
The position of the first minimal value pixel in the image scan order, in world coordinates (millimeters). |
unique |
BOOL |
Boolean indicating if there is only one pixel with the minimal value. |
minValue = Image.getMin(image)
getMinMax()
Returns the minimum and maximum pixel value in an image. Optionally, a pixel region may be provided. Image world coordinate system handling: The output min and max values are specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale. Missing data handling: Missing data pixels are ignored.
maximum, rank, statistics, minimum
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region in which to find the min and max, default is the entire image. |
| Name | Type | Description |
|---|---|---|
minValue |
FLOAT |
The minimum pixel value in world coordinates (millimeters). |
maxValue |
FLOAT |
The maximum pixel value in world coordinates (millimeters). |
minPosition |
OBJECT Point |
The position of the first minimal value pixel in the image scan order, in world coordinates (millimeters). |
maxPosition |
OBJECT Point |
The position of the first maximal value pixel in the image scan order, in world coordinates (millimeters). |
minUnique |
BOOL |
Boolean indicating if there is only one pixel with the minimal value. |
maxUnique |
BOOL |
Boolean indicating if there is only one pixel with the maximal value. |
minValue, maxValue, minPosition, maxPosition, minUnique, maxUnique = Image.getMinMax(image)
getMissingDataFlag()
Gets the missing data setting in the image. 0 means no missing data handling, 1 means that the value 0 is treated as missing data.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
| Name | Type | Description |
|---|---|---|
missingDataFlag |
INT |
Returns the missing data setting. |
local missingDataFlag = Image.getMissingDataFlag(image)
getMissingDataImage()
Creates a binary image indicating the missing data pixels in the source image. Image world coordinate system handling: The output binary image gets the same x,y-origin and x,y-pixelsize as the input image, but the z-origin is set to 0 and the z-pixelsize to 1. Missing data handling: The output image has no missing data flag set as it is a binary image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
missingValue |
INT |
The value to assign result pixels for missing data in the source image. Default = 1 |
dataValue |
INT |
The value to assign result pixels for data in the source image. Default = 0 |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The resulting binary image, always of uint8 pixel type |
result = Image.getMissingDataImage(image)
getMissingDataRegion()
Creates a PixelRegion object of all missing data pixels in the source image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
The region containing all missing data pixels. |
region = Image.getMissingDataRegion(image)
getOrigin()
Retrieves the origin of the image world coordinate in the image. The origin corresponds to the world coordinate of the top-left image pixel.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
| Name | Type | Description |
|---|---|---|
origin |
OBJECT Point |
Returns the origin as a point in 3D. |
local origin = Image.getOrigin(image)
getPercentiles()
Get a set of rank measurement according to the specified percentile levels. Level 0.5 gives the median, level 0.9 give a value larger than 90% of all image pixels, etc. All values are derived from a histogram and are approximate. Optionally, a reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. The default surface is the plane z=0.
statistics
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image, defines the image from which to get pixel value input. |
percentileLevels |
FLOAT |
Percentile levels in the range (0..1) |
region |
CONST_OBJECT Image.PixelRegion |
Input region, default is the entire image. |
referenceSurface |
CONST_OBJECT Shape3D |
Zero-reference plane for pixel world coordinate values. Optional, default is the plane z=0. |
| Name | Type | Description |
|---|---|---|
values |
FLOAT |
Output values |
values = Image.getPercentiles(image, percentileLevels, region, referenceSurface)
getPixel()
Returns the raw pixel value of an image at position (x,y) in pixel coordinates. For monochrome image types this is a single float value, for RGB24 a vector of three float values in the order red, green, blue.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to get the pixel from. |
x |
INT |
The x pixel coordinate. |
y |
INT |
The y pixel coordinate. |
| Name | Type | Description |
|---|---|---|
value |
FLOAT |
The raw pixel value, or a vector of RGB values, or nil for invalid coordinates. |
local value = Image.getPixel(image, 5, 6)
getPixelSize()
Retrieves the pixel size of the image world coordinate system.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
| Name | Type | Description |
|---|---|---|
sizeX |
FLOAT |
Returns the size of a pixel in the X dimension in world coordinate units. |
sizeY |
FLOAT |
Returns the size of a pixel in the Y dimension in world coordinate units. |
sizeZ |
FLOAT |
Returns the size of a pixel in the Z dimension in world coordinate units. |
local sizeX, sizeY, sizeZ = Image.getPixelSize(image)
getSize()
Returns the width and height of an image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to get the size of. |
| Name | Type | Description |
|---|---|---|
width |
INT |
Width of the image in pixels. |
height |
INT |
Height of the image in pixels. |
local width, height = Image.getSize(image)
getSum()
Returns the sum of the pixel values in an image. Image world coordinate system handling: The sum is in world coordinates, i.e., the origin and pixel size in the z-dimension are considered should the image represent a height map, distance or range image. Missing data handling: This operation does not support missing data images, fill in missing data before calling this function.
statistics
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. |
| Name | Type | Description |
|---|---|---|
imageSum |
FLOAT |
The sum of all pixels expressed in world coordinates (millimeters) |
imageSum = Image.getSum(image)
getType()
Returns the pixel type of the image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. |
| Name | Type | Description |
|---|---|---|
pixelType |
ENUM ImageType |
The pixel type (e.g.: uint8, int16, float64). |
local pixelType = Image.getType(image)
getValidDataRegion()
Creates a PixelRegion object of all non-missing data pixels in the source image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
A PixelRegion containing all valid data pixels. |
local region = Image.getValidDataRegion(image)
getWidth()
Returns the width of an image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to get the width of. |
| Name | Type | Description |
|---|---|---|
width |
INT |
Width of the image in pixels. |
local width = Image.getWidth(image)
getWorldZ()
Returns the z-values at given 2D (x,y)-points, interpreting the image as a range image. Linear interpolation is used for positions between the pixel grid positions. For points outside the image the z-origin value is return corresponding to raw pixel value 0. Coordinate system handling: The image world coordinate system is used in this operation, i.e., the input 2D points are interpreted using the pixelsizes and origin in the (x,y)-dimensions and the output z value is also in world coordinates. Missing data handling: Missing data is respected so that missing data pixels are ignored in the interpolation calculation.
getHeight
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. |
points |
CONST_OBJECT Point |
The 2D point to sample at, or a list of 2D points, in world coordinates. |
| Name | Type | Description |
|---|---|---|
valuesZ |
FLOAT |
Z value or values in world coordinates, or nil if unsuccessful. |
local valuesZ = Image.getWorldZ(image, points)
growRegion()
Starting from the seed regions, the regions are expanded to fill the pixel areas whose world pixel values in the image lies between the lower and upper threshold in world coordinates. Pixels with missing data are not grown into. Pixels included in the seed region will always be included in the output region, independent of the corresponding pixel value and missing status. Image world coordinate system handling: The thresholds are interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 or a z-pixelsize different than 1. Missing data handling: Pixels with missing data are not included in the grown region, unless covered by the seed region.
seeded, segmentation, floodfill
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image indicating where the region should grow. |
seedRegion |
CONST_OBJECT Image.PixelRegion |
The region to grow. |
minThreshold |
FLOAT |
Minimum value to allow growth. Optional, default is the smallest representable value. |
maxThreshold |
FLOAT |
Maximum value to allow growth. Optional, default is the largest representable value. |
| Name | Type | Description |
|---|---|---|
grownRegion |
OBJECT Image.PixelRegion |
Result region or nil if operation failed. |
grownRegion = Image.growRegion(image, seedRegion, minThreshold, maxThreshold)
houghTransformCircle()
Finds circle candidates with a given radius in an edge image where any non-zero pixel is considered an edge. The output is an accumulator image binned over circle centers in world coordinates. The world coordinates of the output accumulator directly matches circle centers, i.e. the world coordinates of a maxima in the accumulator image corresponds directly to the input image circle center in world coordinates. Use Image.houghTransformExtremaToCircles to create circles from accumulator image maxima (as a pixel region), or extract maxima as points and use Shape.createCircle(points, radius) directly. Image world coordinate system handling: Input image world coordinates are used. The radius is in world coordinates. The accumulator world coordinates directly relate maxima to circle centers. Pixel values in the input image are interpreted in raw pixel values. Missing data handling: Missing data are interpreted as not edges.
| Name | Type | Description |
|---|---|---|
edgeImage |
CONST_OBJECT Image |
Input image. Supported image types are uint8 and uint16. Non-zero pixels are counted as edges. |
radius |
FLOAT |
The radius of circles to search for, in world coordinates. |
resolutionX |
INT |
The number of bins to use for the x-position of the circles, also the width of the output image, default 200. |
resolutionY |
INT |
The number of bins to use for the y-position of the circles, also the height of the output image, default 200. |
| Name | Type | Description |
|---|---|---|
houghAccumulator |
OBJECT Image |
Circle candidate center accumulator image. |
houghAccumulator = Image.houghTransformCircle(edgeImage, radius, resolutionX, resolutionY)
houghTransformExtremaToCircles()
Converts pixels extracted from an accumulator image obtained from houghTransformCircle to geometrical circles. The accumulator image is required to get the world coordinate system and accumulator values. Results are sorted in descending order by accumulator value. Image world coordinate system handling: Pixel region of extremas should be related to the accumulator image. Circles are returned in world coordinates. Missing data handling: Not applicable, there is no missing data in the input accumulator image.
| Name | Type | Description |
|---|---|---|
accumulatorImage |
CONST_OBJECT Image |
Accumulator image as returned from houghTransformCircle. |
extremalRegion |
CONST_OBJECT Image.PixelRegion |
Pixel region with extremal points extracted from the accumulator image, will be recalculated to the corresponding circles. |
radius |
FLOAT |
Radius of the circles to create. |
| Name | Type | Description |
|---|---|---|
circles |
OBJECT Shape |
Circles as shapes, or nil on error. |
accumulatorValues |
FLOAT |
Accumulator image value corresponding to each circle. |
circles, accumulatorValues = Image.houghTransformExtremaToCircles(accumulatorImage, extremalRegion, radius
houghTransformExtremaToLines()
Converts pixels extracted from an accumulator image obtained from houghTransformLine to geometrical lines. Both the accumulator and edge images are required to get the world coordinate system. Since horizontal lines end up just where the accumulator image wraps around, the accumulator is usually extended with a few extra rows. These may result in duplicate line detections (the direction differ by pi, with opposite sign of the distance to the image center). By default, such duplicate lines are removed but this feature can be turned off. The accumulator value corresponding to each line candidate is returned. Results are sorted in descending order by accumulator value. Image world coordinate system handling: Pixel region of extremas should be related to the accumulator image. Lines are returned in world coordinates of the original input image. Missing data handling: Not applicable, there is no missing data in the input accumulator image.
| Name | Type | Description |
|---|---|---|
accumulatorImage |
CONST_OBJECT Image |
Accumulator image as returned from houghTransformLines. |
extremalRegion |
CONST_OBJECT Image.PixelRegion |
Pixel region with extremal points extracted from the accumulator image, will be recalculated to the corresponding lines. |
edgeImage |
CONST_OBJECT Image |
Input image as sent to houghTransformLine, used for coordinate reference. |
removeDuplicates |
BOOL |
Flag indicating if duplicate lines should be removed, default is true. |
| Name | Type | Description |
|---|---|---|
lines |
OBJECT Shape |
Lines as shapes, or nil on error. |
accumulatorValues |
FLOAT |
Accumulator image value corresponding to each line. |
lines = Image.houghTransformExtremaToLines(accumulatorImage, extremalRegion, edgeImage, removeDuplicates)
houghTransformLine()
Finds line candidates in an edge image where any non-zero pixel is considered an edge. The output is an accumulator image binned over line candidate direction and signed distance from the center of the input image. E.g. a line candidate with direction pi/2 and distance -5 is a vertical line located five world coordinate units to the left of the center point of the input image. Line candidates are on the form x*sin(theta) + y*cos(theta) = d, where x and y are input image positions relative to the center of the input image, d is the signed distance from the center of the input image and theta is the line direction. All are expressed in world coordinates. d is binned over distanceBins bins which also is the width of the output image. Theta is binned over directionBins bins. The range of theta is from zero to pi, d is from minus to plus half the diagonal of the input image. Since the direction parameter is circular in nature, a maxima at the upper and lower accumulator image border (theta is zero or pi) with opposite signs of d correspond to the same line. Since maxima extraction routines tend to skip maxima close to image borders, a few extra rows are added to the bottom of the accumulator image, corresponding to the first rows of accumulators. The number of extra rows is set by the overlapBins parameters, recommended to be set to the maxima extraction filter size. The accumulator image height is thus directionBins + overlapBins. Use houghTransformExtremaToLines to transform extrema from the accumulator image into Shape lines. Image world coordinate system handling: Input image world coordinates are used. All output values are with respect to the center of the input image. The output image world coordinates are set to directly get d and theta values. Raw pixel values of the input image are used. Missing data handling: Missing data are interpreted as not edges.
| Name | Type | Description |
|---|---|---|
edgeImage |
CONST_OBJECT Image |
Input image. Supported image types are uint8 and uint16. Non-zero pixels are counted as edges. |
distanceBins |
INT |
The number of bins to use for the distance to the line from the edge image center, the width of the output image, default 200. |
directionBins |
INT |
The number of bins to use for the direction of the line, the height of the output image, default 360. |
overlapBins |
INT |
The number of extra rows to add at the bottom of the accumulator image, overlapping with the first rows. Recommended value is the size of the maxima filter to be used, default is 5. |
| Name | Type | Description |
|---|---|---|
houghAccumulator |
OBJECT Image |
Line candidate accumulator image. |
houghAccumulator = Image.houghTransformLine(edgeImage, distanceBins, directionBins, overlapBins)
inpaint()
Replaces the image content in a specified region with the content around the region. This is done in an iterative manner and increasing the radius increases the speed of the algorithm, at the cost of quality of the result. Image world coordinate system handling: The world coordinate system of the input image is not used. The output will have the same coordinate system as the input image. Missing data handling: Operation is performed in raw pixel values. If there are missing data along the borders of the region it will be used for inpainting.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image in which to perform inpainting. |
region |
CONST_OBJECT Image.PixelRegion |
The region to be replaced. |
radius |
FLOAT |
Pixel radius used by inpainting algorithm. Default is 3.0. |
method |
ENUM InpaintMethod |
Inpainting method. Default is NAVIER_STOKES. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The resulting image. |
local result = Image.inpaint(image, region)
invert()
Inverts the pixel values in the image, so that dark becomes bright and vice versa. The operation imOutput = getMax(imInput) - imInput. The function only accepts unsigned integer pixel types, to invert signed pixel type use a negation instead. To do an inversion in the sense 1/x use the pow-function. Image world coordinate system handling: The output image keeps the coordinate system of the input image. Missing data handling: A missing data pixel in the input image results in a missing data pixel in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
brightness, contrast, inverse
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The inverted image. |
result = Image.invert(image)
invertInplace()
Inplace version of the Image.invert function that modifies the input image. See base function for full documentation.
brightness, contrast, inverse
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The source image. This image is overwritten with the result image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.invertInplace(image)
isEqual()
Checks if two images are equal, both in terms of size, type and pixel content. This function disregards the missing data flag and image world coordinate information and looks only at raw pixel values.
compare, similar, check
| Name | Type | Description |
|---|---|---|
image1 |
CONST_OBJECT Image |
The first source image. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
BOOL |
True if the images have identical size and pixel type, and equal contents at each pixel. |
result = Image.isEqual(image1, image2)
isWithinBounds()
Checks whether a pixel coordinate is within the bounds of the image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
|
x |
INT |
The x pixel coordinate of the point to be checked. |
y |
INT |
The y pixel coordinate of the point to be checked. |
| Name | Type | Description |
|---|---|---|
isInBounds |
BOOL |
Returns true if the point is within the image, false otherwise. |
local isInBounds = Image.isWithinBounds(image, 15, 15)
laplace()
Applies a Laplace filter to the input image, i.e., the sum of the local second-order gradients in the x- and y-directions. Image world coordinate system handling: The Laplace filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.
convolve, derivative, gradient, edge
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, float32 and float64. |
kernelSizePix |
INT |
Size of the kernel, must be positive, odd and not larger than 29. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Pixel values outside the region are undefined. |
| Name | Type | Description |
|---|---|---|
laplaceImage |
OBJECT Image |
Output image with the Laplace values. |
laplaceImage = Image.laplace(image, kernelSizePix)
load()
Loads an image from the specified file path. The format is defined by the file extension: .bmp: Bitmap .png: PNG .jpg: JPEG (not supported by all devices) .json: JSON .msgpack: MessagePack
| Name | Type | Description |
|---|---|---|
filepath |
STRING |
The path and name of the file to load the image from. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The Image object which is loaded. |
local image = Image.load("resources/image.bmp")
max()
Creates an image with the maximum pixel values of the source images. The images must be of equal size and pixel type. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. The input images are allowed to have different image world coordinate systems, but only the z-pixelsizes and z-origins are utilized, pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image.
arithmetic, compare, maximum
| Name | Type | Description |
|---|---|---|
image1 |
CONST_OBJECT Image |
The first source image. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The maximum image. |
result = Image.max(image1, image2)
maxInplace()
Inplace version of the Image.max function which modifies the first input image to contain the pixelwise maximum of the input images. See base function for full documentation.
arithmetic, compare, maximum
| Name | Type | Description |
|---|---|---|
image1 |
OBJECT Image |
The first source image. This image is overwritten with the pixelwise maximum. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.maxInplace(image1, image2)
median()
Applies median filter to the image to smooth and remove noise. Image world coordinate system handling: The median filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image. Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.
denoise, edge preserving, filter, smooth
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, int16 and float32. |
kernelSizePix |
INT |
Size of the kernel, must be positive and odd. For kernel sizes larger than 5 the only supported image type is uint8. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Output pixel values outside the region are undefined. |
fillMissingData |
BOOL |
Optional flag to also fill in missing data pixels when smoothing images containing missing data. Default is false. |
| Name | Type | Description |
|---|---|---|
medianImage |
OBJECT Image |
Output image blurred by the median filter. |
medianImage = Image.median(image, kernelSizePix)
min()
Creates an image with the minimum pixel values of the source images. The images must be of equal size and pixel type. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. The input images are allowed to have different image world coordinate systems, but only the z-pixelsizes and z-origins are utilized, pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image.
arithmetic, compare, minimum
| Name | Type | Description |
|---|---|---|
image1 |
CONST_OBJECT Image |
The first source image. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The minimum image. |
result = Image.min(image1, image2)
minInplace()
Inplace version of the Image.min function which modifies the first input image to contain the pixelwise minimum of the input images. See base function for full documentation.
arithmetic, compare, minimum
| Name | Type | Description |
|---|---|---|
image1 |
OBJECT Image |
The first source image. This image is overwritten with the pixelwise minimum. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.minInplace(image1, image2)
mirror()
Mirrors an image in the horizontal or vertical axis. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is mirrored. Missing data handling: All missing data values will be retained after mirroring.
flip
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. |
mirrorHorizontally |
BOOL |
Set to true to mirror horizontally in the vertical axis, set to false to mirror vertically in the horizontal axis. |
| Name | Type | Description |
|---|---|---|
mirroredImage |
OBJECT Image |
The mirrored image |
mirroredImage = Image.mirror(image, mirrorHorizontally)
missingDataReduce()
Reduces missing data pixels in an image by using valid values in the neighborhood. Valid pixel values are unaffected. This will fill in scattered missing data values but larger patches of missing data will remain. The type of operation performed to fill a missing pixel is selected using the method parameter. Optionally, reduction of missing data can be limited to a region in the image. Valid pixel values within a neighborhood but outside the region will still be used to fill missing data. To fill a missing pixel, at least one quarter of the neighbor pixels need to have valid values. The available methods are: MAX - Sets missing pixels to the maximum valid value in the neighborhood. MIN - Sets missing pixels to the minimum valid value in the neighborhood. MEAN - Sets missing pixels to the mean of all valid values in the neighborhood. MEDIAN - Sets missing pixels to the median of all valid values in the neighborhood. EDGE - Fills missing values by edge-preserving interpolation among pixels in the 3x3 pixel neighborhood. A missing data pixel will be filled in only if there are valid values on both sides of a pixel. For all methods except EDGE, the neighborhood is nSize-by-nSize pixels. nSize must be odd and at least three. For method EDGE, nSize determines how many times the algorithm will be repeated. For EDGE, nSize must be a positive integer.
| Name | Type | Description |
|---|---|---|
inputImage |
CONST_OBJECT Image |
The input image. An error is returned if the input image does not have the missing data flag set. |
method |
ENUM MissingDataMethod |
Method to be used for reducing missing data. |
nSize |
INT |
The size of the neighborhood for most methods, the number of iterations for EDGE. Default is 3. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the filter operation is only performed within this region. This can save a lot of computation time, if the region is small. |
| Name | Type | Description |
|---|---|---|
outputImage |
OBJECT Image |
The output image, or nil if an error occurred. |
outputImage = Image.missingDataReduce(inputImage, method, nSize, region)
missingDataSetAll()
Sets all missing data pixels in the entire image or within a specified region to a given value. All missing pixels are set and the missing data flag of the image is cleared. If a region is provided, only pixels within the region are considered. The missing data flag of the image is still cleared, leaving any pixels with missing data outside the region in an undetermined state. Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. The output image inherits the image world coordinate system of the input image. Missing data handling: The missing data flag is removed from the output image, also if the operation is only performed within a region of interest.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The input image. |
valueWorld |
FLOAT |
The value to set, in world coordinates considering z-origin and z-pixelsize if applicable. |
region |
CONST_OBJECT Image.PixelRegion |
A region of interest to operate within. Optional, default is operate on the entire image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The output image. |
result = Image.missingDataSetAll(image, value, region)
missingDataSetAllInplace()
Inplace version of the Image.missingDataSetAll function that modifies the input image. See base function for full documentation.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to set missing data in. This image is overwritten with the result image. |
valueWorld |
FLOAT |
The value to set, in world coordinates considering z-origin and z-pixelsize if applicable. |
region |
CONST_OBJECT Image.PixelRegion |
A region of interest to operate within. Optional, default is operate on the entire image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.missingDataSetAllInplace(image, value, region)
missingDataSetSurface()
Sets all missing data pixels to the surface value, values are clamped to the representable range of the image. All valid values are left unchanged. If a region not covering the full image is used, any missing data outside the region will be left in an undetermined state. Currently, only a plane surface represented as a Shape3D is supported, other surface types may be supported in the future. Image world coordinate system handling: The surface is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: This function replaces all missing data pixels with the surface value. The missing data flag for the output image is removed, also when this operation is performed only within a specified region of interest.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to set missing data in. |
surface |
CONST_OBJECT Shape3D |
The surface to clamp to, represented as a Shape3D. Currently only a plane type is supported, in future more surface types may be supported. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region where the operation is to be performed, default is the full image. |
| Name | Type | Description |
|---|---|---|
clampedImage |
OBJECT Image |
The image without missing data. Nil if an error occurred. |
clampedImage = Image.missingDataSetSurface(image, surface, region)
missingDataSetSurfaceInplace()
Inplace version of the Image.missingDataSetSurface function which modifies the input image by adding the value of a given plane. See base function for full documentation.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to set missing data in. This image is overwritten and the missing data is set according to the surface value. |
surface |
CONST_OBJECT Shape3D |
The surface to clamp to, represented as a Shape3D. Currently only a plane type is supported, in future more surface types may be supported. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region where the operation is to be performed, default is the full image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.missingDataSetSurfaceInplace(image, surface, region)
morphology()
A morphological transformation applied to grayscale images. The possible transformation types are: ERODE, DILATE, OPEN, CLOSE, GRADIENT, TOPHAT and BLACKHAT. A circular structuring element/kernel is used for all types. The diameter of the kernel can be specified by diameterPix. For erosion the basic idea is just like soil erosion, it erodes away the boundaries of an object making it thinner. The dilation is the opposite transformation. The elements of the kernel contain: 0-background or 1-foreground. It is centered at each image pixel and defines the neighborhood pixels to be used. For grayscale erosion the new pixel value corresponds to the minimum value of the image pixels under the structuring element foreground. Similarly, for grayscale dilation the maximum of the neighborhood is used. The remaining transformations are: opening - erosion followed by dilation; closing - dilation followed by erosion; morphological gradient - difference between dilation and erosion; top hat - difference between input image and opening; black hat - difference between closing and input image. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The diameter of the structuring element is in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.
binary, blackhat, close, erode, open, tophat, dilate
| Name | Type | Description |
|---|---|---|
imageIn |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, int8, int16, int32, float32 and float64. |
diameterPix |
INT |
The diameter of the circular structuring element/kernel in pixels. The value must be odd and between 3 and 51. |
transform |
The morphological transformation, possible types are: ERODE, DILATE, OPEN, CLOSE, GRADIENT, TOPHAT and BLACKHAT. |
| Name | Type | Description |
|---|---|---|
imageOut |
OBJECT Image |
Morphology transformed image |
imageOut = Image.morphology(imageIn, diameterPix, transform)
mosaic()
Crops an image into a vector of smaller tiles. The mosaic tiles can be specified to overlap. A valid tile must be completely within the source image, i.e., tiles that would partly extend outside the image at the right and bottom borders of the source image are not included in the output vector. The vector of tiles is sorted row wise so that all the tiles covering the uppermost part of the image come first.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. |
tileWidth |
INT |
The width of a tile in pixels. |
tileHeight |
INT |
The height of a tile in pixels. |
xOverlap |
INT |
Optional overlap between tiles in the x-direction in pixels. Default is no overlap, i.e., 0 pixels. |
yOverlap |
INT |
Optional overlap between tiles in the y-direction in pixels. Default is no overlap, i.e., 0 pixels. |
| Name | Type | Description |
|---|---|---|
imageTiles |
OBJECT Image |
Vector of image tiles. |
xTileCount |
INT |
Number of tiles in the x-direction. |
yTileCount |
INT |
Number if tiles in the y-direction. |
local imageTiles, nx, ny = Image.mosaic(im, 32, 32)
multiply()
Multiplies two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate value. The second image is treated as a unit-less modifier and it must therefore have a standard image world coordinate system with pixel sizes all equal to 1 and origins equal to 0. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. Note that it is possible to obtain 0 as result of the multiplication and that such pixels then will be considered as missing data in subsequent processing steps.
arithmetic, scale, times
| Name | Type | Description |
|---|---|---|
image1 |
CONST_OBJECT Image |
The first source image. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The product image. |
result = Image.multiply(image1, image2)
multiplyAddConstant()
Multiplies an image pixelwise by a constant alpha and then adds a second constant beta: alpha*Image + beta. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type, with an exception for images containing missing data, see below. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters, considering the z-origin and z-pixelsize. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
arithmetic, scale, offset
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
alpha |
FLOAT |
The constant to multiply with. |
beta |
FLOAT |
The constant to add. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The resulting image. |
result = Image.multiplyAddConstant(image, alpha, beta)
multiplyAddConstantInplace()
Inplace version of Image.multiplyAddConstant function which modifies the input image. See base function for full documentation.
arithmetic, scale, offset
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The source image. This image is overwritten with the result image. |
alpha |
FLOAT |
The constant to multiply with. |
beta |
FLOAT |
The constant to add. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.multiplyAddConstantInplace(image, alpha, beta)
multiplyConstant()
Multiplies all pixels in the image with a constant value. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type, with an exception for images containing missing data, see below. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, multiplication of the world z-value is done, considering the z-origin and z-pixelsize. The image metadata from the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. Note that it is possible to obtain 0 as result of the multiplication and that such pixels then will be considered as missing data in subsequent processing steps.
arithmetic, scale, times
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
constant |
FLOAT |
The constant. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The multiplied image. |
result = Image.multiplyConstant(image, 2.0)
multiplyConstantInplace()
Inplace version of Image.multiplyConstant function which modifies the input image. See base function for full documentation.
arithmetic, scale, times
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The source image. This image is overwritten with the result image. |
constant |
FLOAT |
The constant. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.multiplyConstantInplace(image, 2.0)
multiplyInplace()
Inplace version of the Image.multiply function which modifies the first input image to contain the product of the input images. See base function for full documentation.
arithmetic, scale, times
| Name | Type | Description |
|---|---|---|
image1 |
OBJECT Image |
The first source image. This image is overwritten with the product. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.multiplyInplace(image1, image2)
normalize()
Scales the raw pixel values linearly so that all pixels fit into a given range (lowerBound, upperBound). Keeps the world values constant. Target bounds outside the representable range of the image type are accepted. In that case, pixel values are clamped to the representable range. Image world coordinate system handling: The world coordinate system of the output image along the value axis z is chosen such that the world pixel values remains unchanged unless clamping occurs. For integer type images, rounding to integer raw pixel values will change the world values slightly. Other meta data are copied from the input image. Missing data handling: Pixels with missing data remain marked as missing in the output. For images with the missing data flag set, raw pixel values are clamped to 1 instead of 0 to avoid introducing more pixels marked as missing.
contrast, intensity, scale, stretch, equalize
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, int8, int16, int32, float32 and float64. |
lowerBound |
FLOAT |
Lower bound (raw pixel value). Default value is minimum value of underlying datatype. |
upperBound |
FLOAT |
Upper bound (raw pixel value). Default value is maximum value of underlying datatype. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
| Name | Type | Description |
|---|---|---|
normalizedImage |
OBJECT Image |
Normalized image |
normalizedImage = Image.normalize(image)
pad()
Image padding, adds a border to the image. Image world coordinate system handling: The image world coordinate system is used to update the output image origin, it is calculated as follows: (Oxout, Oyout, Ozout) = (Oxin - pixelSizeX * leftPaddingPix, Oyin - pixelSizeY * topPaddingPix, Ozin), the world pixel sizes remain the same. The boundary paddings are in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not use the missing data flag. If the padding contains zeros it will be treated as missing data if the flag is on.
replicate, extend
| Name | Type | Description |
|---|---|---|
imageIn |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB. |
topPaddingPix |
INT |
The top padding in pixels |
bottomPaddingPix |
INT |
The bottom padding in pixels |
leftPaddingPix |
INT |
The left padding in pixels |
rightPaddingPix |
INT |
The right padding in pixels |
borderType |
ENUM BorderType |
The border type to use for the padding, currently CONSTANT, REPLICATE, REFLECT and WRAP are available. If the border type is not CONSTANT the padding value is not used. |
intensity |
FLOAT |
The padding intensity. In case the image type is RGB then an array of 3 elements (one per channel) must be provided. If the border type is not CONSTANT this value does not need to be specified. |
| Name | Type | Description |
|---|---|---|
imageOut |
OBJECT Image |
Padded Image |
imageOut = Image.pad(imageIn, topPaddingPix, bottomPaddingPix, leftPaddingPix, rightPaddingPix, borderType, intensity)
pow()
Applies an exponent to the value at each pixel. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel data type respectively. Image world coordinate system handling: The z-scale of the image is considered, but the operation is not implemented for images with z-origin different from 0.0. The image metadata from the input image is copied to the output image. Missing data handling: In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
arithmetic, cube, exp, exponent, inverse, invert, sqr, sqrt, square, power
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image. |
exponent |
FLOAT |
The exponent. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The processed image. |
result = Image.pow(image, exponent)
powInplace()
Inplace version of the Image.pow function which modifies the input image. See base function for full documentation.
arithmetic, cube, exp, exponent, inverse, invert, sqr, sqrt, square, power
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The source image. This image is overwritten with the result image. |
exponent |
FLOAT |
The exponent. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
A reference to the result image. |
Image.powInplace(image, exponent)
renderPlane()
Renders a plane to an image, clamping values to the representable range of the image. The output image is of the same type as the input image. Image world coordinate system handling: The surface is rendered in the world space defined by the reference image, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the reference image is copied to the output image. Missing data handling: The missing data flag of the reference image is copied to the output image. If the flag is set, raw pixel values are clamped to 1 instead of 0 to avoid generating pixels with missing data.
draw
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The reference image defining the output image size, type and coordinate system. |
plane |
CONST_OBJECT Shape3D |
The plane to render, should be a plane shape. |
| Name | Type | Description |
|---|---|---|
renderedImage |
OBJECT Image |
The image with the rendered plane. Nil if an error occurred. |
renderedImage = Image.renderPlane(image, plane)
renderPlaneInplace()
Inplace version of the Image.renderPlane function which modifies the input image by adding the value of a given plane. See base function for full documentation.
draw
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
Reference input image. This image is overwritten with the result image. |
plane |
CONST_OBJECT Shape3D |
The plane to render, must be a Shape3D plane. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.renderPlaneInplace(image, plane)
renderText()
Renders text into an image by modifying the pixel values. Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The font parameters and text position are in pixel units, i.e., not scaled with the world pixel sizes in x and y. Missing data handling: This function does not use the missing data flag.
characters, letters, draw
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to render the text into. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB. |
text |
STRING |
The characters that cannot be rendered using the specified font are replaced by question marks. |
positionWorld |
CONST_OBJECT Point |
The position of the text inside the image, in world coordinates. The text is aligned to the bottom-left corner. |
fontSizePix |
INT |
The font size in pixels. |
fontThicknessPix |
INT |
The font line thickness radius in pixels. To calculate the overall thickness the following equation can be used: thickness=(fontThicknessPix*2+1). |
value |
FLOAT |
The text (intensity/color) value. In case the image type is RGB then an array of 3 elements (one per channel) must be provided. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
Image with rendered text |
image = Image.renderText(image, text, positionWorld, fontSizePix, fontThicknessPix, value)
renderTextInplace()
Inplace version of the Image.renderText function that modifies the input image. See base function for full documentation.
characters, letters, draw
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to render the text into. This image is overwritten with the rendered text. Supported image types are uint8, uint16, int8, int16, int32, float32, float64 and RGB. |
text |
STRING |
The characters that cannot be rendered using the specified font are replaced by question marks. |
positionWorld |
CONST_OBJECT Point |
The position of the text inside the image, in world coordinates. The text is aligned to the bottom-left corner. |
fontSizePix |
INT |
The font size in pixels. |
fontThicknessPix |
INT |
The font line thickness radius in pixels. To calculate the overall thickness the following equation can be used: thickness=(fontThicknessPix*2+1). |
value |
FLOAT |
The text (intensity/color) value. In case the image type is RGB then an array of 3 elements (one per channel) must be provided. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.renderTextInplace(image, text, positionWorld, fontSizePix, fontThicknessPix, value)
replace()
Replaces the image content in a specified region with the content of another image. The images must have the same pixel type. Image world coordinate system handling: The world coordinate systems of the input images are not used. The output will have the same coordinate system as the first input image. Missing data handling: Raw pixel values are copied as they are. If there are missing data within the region in the replacing image, the source image pixels will be replaced by missing data.
| Name | Type | Description |
|---|---|---|
sourceImage |
CONST_OBJECT Image |
Base image onto which the other image is painted. |
replacingImage |
CONST_OBJECT Image |
The image containing the information to replace with. |
region |
CONST_OBJECT Image.PixelRegion |
The region to replace. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The composed image. |
local result = Image.replace(sourceImage, replacingImage, region)
replaceInplace()
Inplace version of the Image.replace function which modifies the first input image by replacing pixel values with pixel values from another image. See base function for full documentation.
| Name | Type | Description |
|---|---|---|
sourceImage |
OBJECT Image |
Base image onto which the other image is painted. |
replacingImage |
CONST_OBJECT Image |
The image containing the information to replace with. |
region |
CONST_OBJECT Image.PixelRegion |
The region to replace. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
local result = Image.replaceInplace(sourceImage, replacingImage, region)
resize()
Resizes an image to a given size in pixels. Different interpolation methods can be used. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
decimate, downsample, resample, subsample, transform, upsample, scale
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image |
width |
INT |
The width of the result |
height |
INT |
The height of the result. |
method |
ENUM InterpolationMethod |
The resampling method. Default is LINEAR. |
| Name | Type | Description |
|---|---|---|
resizedImage |
OBJECT Image |
Image with new size. |
resizedImage = Image.resize(image, 300, 400, "LINEAR")
resizeScale()
Resizes an image by a scale factor. Different interpolation methods can be used. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
decimate, downsample, resample, subsample, transform, upsample, scale
Image.Pyramid, Image.toSquarePixels, Image.transform, Image.resize
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image |
fx |
FLOAT |
Scaling factor along the x-axis. |
fy |
FLOAT |
Scaling factor along the y-axis. Optional, if omitted the same as the x-scale is used. |
method |
ENUM InterpolationMethod |
The resampling method. Default is LINEAR. |
| Name | Type | Description |
|---|---|---|
resizedImage |
OBJECT Image |
Image with new size. |
resizedImage = Image.resizeScale(image, 1.5, 1.5, "LINEAR")
rotate()
Rotates an image around the center of the image. Optionally a different origin of rotation can be specified. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the input image and the transformed image is by default (output grid SAME) repainted onto this coordinate system. Using output grid FULL, the output image size and origin is set to fit the entire output. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
Image.cropRectify, Image.mirror, Image.transform, Image.rotate90
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image |
rotationRad |
FLOAT |
Rotation in radians. As the image has a left-handed coordinate system, a positive rotation is in a counter clockwise direction. |
origin |
CONST_OBJECT Point |
Optional origin of rotation if other than center of image. Represented as a 2D Point type. |
method |
ENUM InterpolationMethod |
The resampling method. |
grid |
ENUM OutputGrid |
The pixel grid to use for the output, default is SAME, the same as the input image. |
| Name | Type | Description |
|---|---|---|
rotatedImage |
OBJECT Image |
The rotated image. |
rotatedImage = Image.rotate(image, rotationRad)
rotate90()
Rotates an image +90, -90 or 180 degrees. A positive rotation is in the clockwise direction. The pixels are rearranged and no interpolation takes place, making the operation faster than a general rotation. Image world coordinate system handling: For plus and minus 90 degree rotations, the x- and y-pixel sizes are swapped so that the width and height are also swapped. The image origin is copied from the input image. Missing data handling: Missing data is rotated in the same way as the input image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image |
rotationSteps |
INT |
The number of 90-degree steps to rotate the image in, e.g. -1, 1 or 2. Other integers are allowed, representing the same rotations. A positive rotation is in a clockwise direction. |
| Name | Type | Description |
|---|---|---|
rotatedImage |
OBJECT Image |
The rotated image. |
rotatedImage = Image.rotate90(image, rotationSteps)
save()
Saves an image to the specified file path. Overwrites the file if it already exists. Supported pixel types are: UINT8, UINT16, INT8, INT16, INT32, FLOAT32 and FLOAT64. The format is defined by the file extension: .bmp: Bitmap, no data compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are not saved. .png: PNG, lossless data compression. (Compression level can be controlled by compression parameter. Allowed values are "0" to "9". Default is "6".) Image origin, pixel size and missing data flag are not saved. For pixel types INT8, INT16, INT32, FLOAT32 and FLOAT64 the values are clamped to 0-255. .jpg: JPEG, lossy data compression. Not supported on all devices. (Quality can be controlled by compression parameter. Allowed values are "0" to "100". Default is "95") Image origin, pixel size and missing data flag are not saved. .json: JSON, no compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are saved. .msgpack: MessagePack, no compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are saved.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to save. |
filepath |
STRING |
The path and name of the file to write the image to. |
compression |
STRING |
Optional parameters controlling compression ratio for certain file formats. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true on success. |
Image.save(image, "private/image.bmp")
setAll()
Sets all raw pixel values in an image to the specified value. Currently only supports scalar pixel types, i.e., not RGB. Pixels with missing data are also set. Setting all pixels to zero on an image with the global missing data flag set, all pixels will be marked as missing.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image. |
value |
FLOAT |
The raw pixel value to set. |
Image.setAll(image, 0.0)
setColumn()
Fills in a column of an image with the value(s) provided. Note that this function operates inplace. If a scalar value is provided, all rows from startRow to the image height will be filled with the value. If the provided value(s) is a vector of length N, N rows will be filled with these values starting at row startRow. Coordinate system handling: The image world coordinate system is only considered along the value range. Missing data handling: A missing data image may be used as the target image. Values evaluating to the origin in z will become missing in the target.
Image.extractColumnProfile, Image.extractProfile, Image.extractRowProfile, Image.setColumnProfile, Image.setRowProfile, Image.subtractProfile, Image.setRow
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The target image. All pixel types except RGB are supported. |
values |
FLOAT |
The source profile. |
column |
INT |
Index of column to fill, zero-based. |
startRow |
INT |
The first row index to fill, zero-based. If no index is given 0 will be used. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if values could be set. |
local success = Image.setColumn(image, values, column, startRow)
setColumnProfile()
Fills in a column of an image with the values taken from a profile. Note that this function operates inplace. The values in the profile is filled into the image column starting at row startRow. The number of values set are equal to the length of the profile. Coordinate system handling: The image world coordinate system is only considered along the value range, i.e., the profile z origin and pixelsize is used to scale the profile before placing it in the image. The x and y coordinate of the profile and image are ignored and the values are simply placed in the designated image pixels. Missing data handling: If the source profile contains invalid points the target image must be a missing data image. Missing data is propagated from profile to image.
Image.extractColumnProfile, Image.extractProfile, Image.extractRowProfile, Image.subtractProfile, Profile.toImage, Image.setRowProfile
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The target image. All pixel types except RGB are supported. |
profile |
CONST_OBJECT Profile |
The source profile. |
column |
INT |
Index of column to fill, zero-based. |
startRow |
INT |
The first row index to fill, zero-based. If no index is given 0 will be used. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if values could be set. |
local success = Image.setColumnProfile(image, profile, column, startRow)
setMissingDataFlag()
Sets the missing data setting in the image. 0 means no missing data handling, 1 means that the value 0 is treated as missing data.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
|
missingDataFlag |
INT |
0 means no missing data handling, 1 means that the value 0 is treated as missing data. |
Image.setMissingDataFlag(image, 1)
setOrigin()
Sets the origin of the image world coordinate system in the image. The origin corresponds to the image world coordinate of the top-left pixel. If a 2D point is provided, the origin is unchanged in the z-direction.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
|
origin |
CONST_OBJECT Point |
A 3D point describing the world coordinate of the top-left image pixel. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successfully set the origin. |
local success = Image.setOrigin(image, origin)
setOriginZ()
Sets the z-origin of the image world coordinate system in the image.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
Image object to update. |
originZ |
FLOAT |
The new z-origin. |
Image.setOriginZ(image, originZ)
setPixel()
Set the raw pixel value or a vector of pixel values in an image at position(s) (x,y) to the given raw pixel value. For monochrome image types this is a single float value, for RGB24 a vector of three float values in the order red, green, blue.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image to set the pixels to |
x |
INT |
The x coordinate, or a vector of x coordinates, of the pixel(s) to set. |
y |
INT |
The y coordinate, or a vector of y coordinates, of the pixel(s) to set. |
value |
FLOAT |
The raw pixel value, or a vector of RGB values, to set. |
Image.setPixel(image, 5, 6, 127)
Image.setPixel(imageRGB, {5, 5}, {6, 7}, {0, 127, 255})
setPixelSize()
Sets the pixel size in world coordinates. If the size in the Z direction is omitted, the Z size is unchanged.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
|
sizeX |
FLOAT |
The size of a pixel in the X dimension in world coordinate units. |
sizeY |
FLOAT |
The size of a pixel in the Y dimension in world coordinate units. |
sizeZ |
FLOAT |
The size of a pixel in the Z dimension in world coordinate units (optional). |
Image.setPixelSize(image, sizeX, sizeY, sizeZ)
setPixelSizeZ()
Sets the pixel size in the z-dimension in world coordinates, e.g., the number of millimeters each pixel value integer increment corresponds to.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
|
sizeZ |
FLOAT |
The size/scale along the z-dimension. |
Image.setPixelSizeZ(image, sizeZ)
setRow()
Fills in a row of an image with the value(s) provided. Note that this function operates inplace. If a scalar value is provided, all columns from startColumn to the image width will be filled with the value. If the provided value(s) is a vector of length N, N columns will be filled with these values starting at column startColumn. Coordinate system handling: The image world coordinate system is only considered along the value range. Missing data handling: A missing data image may be used as the target image. Values evaluating to the origin in z will become missing in the target.
Image.extractColumnProfile, Image.extractProfile, Image.extractRowProfile, Image.setColumnProfile, Image.setRowProfile, Image.subtractProfile, Profile.toImage, Image.setColumn
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The target image. All pixel types except RGB are supported. |
values |
FLOAT |
The source data. |
row |
INT |
Index of row to fill, zero-based. |
startColumn |
INT |
The first column index to fill, zero-based. If no index is given 0 will be used. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if values could be set. |
local success = Image.setRow(image, values, row, startColumn)
setRowProfile()
Fills in a row of an image with the values taken from a profile. Note that this function operates inplace. The values in the profile is filled into the image row starting at column startColumn. The number of values set are equal to the length of the profile. Coordinate system handling: The image world coordinate system is only considered along the value range, i.e., the profile z origin and pixelsize is used to scale the profile before placing it in the image. The x and y coordinate of the profile and image are ignored and the values are simply placed in the designated image pixels. Missing data handling: If the source profile contains invalid points the target image must be a missing data image. Missing data is propagated from profile to image.
Image.extractColumnProfile, Image.extractProfile, Image.extractRowProfile, Image.subtractProfile, Profile.toImage, Image.setColumnProfile
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The target image. All pixel types except RGB are supported. |
profile |
CONST_OBJECT Profile |
The source profile. |
row |
INT |
Index of row to fill, zero-based. |
startColumn |
INT |
The first column index to fill, zero-based. If no index is given 0 will be used. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if values could be set. |
local success = Image.setRowProfile(image, profile, row, startColumn)
sobel()
Applies the standard 3x3 Sobel filter operator to find gradients and edges in the x- and y-directions. Image world coordinate system handling: The Sobel filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.
convolve, derivative, gradient, edge
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, int16, float32 and float64. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. Pixel values outside the region are undefined. |
| Name | Type | Description |
|---|---|---|
gx |
OBJECT Image |
Output image with gradient x. |
gy |
OBJECT Image |
Output image with gradient y. |
gx, gy = Image.sobel(image)
sobelMagnitude()
Calculates the magnitude of the standard 3x3 Sobel operator gradient responses dx and dy to find edges in the input image. Image world coordinate system handling: The Sobel filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale. Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.
convolve, derivative, gradient, edge
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. Supported image types are uint8, uint16, uint32, int8, int16, int32, float32 and float64. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. Enter the value nil to filter the entire image. If a non-empty region is supplied, the filter operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
metric |
ENUM MetricType |
Select if the faster abs(dx)+abs(dy) or the more precise sqrt(dx2+dy2) should be used. Default is 'ABS'. |
| Name | Type | Description |
|---|---|---|
imageMag |
OBJECT Image |
Output image with gradient magnitude. |
imageMag = Image.sobelMagnitude(image)
splitRGB()
Splits an RGB image into the individual R, G, B color components. The input RGB image must be of 8-bit RGB type.
color
| Name | Type | Description |
|---|---|---|
imageRGB |
CONST_OBJECT Image |
RGB image (8-bit) to convert. |
| Name | Type | Description |
|---|---|---|
imageR |
OBJECT Image |
Red component as image. |
imageG |
OBJECT Image |
Green component as image. |
imageB |
OBJECT Image |
Blue component as image. |
imageR, imageG, imageB = Image.splitRGB(imageRGB)
subtract()
Subtracts two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below. Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation. For unsigned integer types it can be useful to first apply Image.adjustOriginZ() to image1 to avoid clamping the results to 0. For images A, B subtracting B from A would cause clamping when values in B are larger than those in A by such a large amount that the difference exceeds the Z-origin of A. By adjusting the origin of A to a smaller value this can be remedied. Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.
arithmetic, difference, minus
| Name | Type | Description |
|---|---|---|
image1 |
CONST_OBJECT Image |
The first source image. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
The difference image. |
result = Image.subtract(image1, image2)
subtractInplace()
Inplace version of the Image.subtract function which modifies the first input image to contain the difference of the input images. See base function for full documentation.
arithmetic, difference, minus
| Name | Type | Description |
|---|---|---|
image1 |
OBJECT Image |
The first source image. This image is overwritten with the difference. |
image2 |
CONST_OBJECT Image |
The second source image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.subtractInplace(image1, image2)
subtractPlane()
Subtracts a plane from an image. For every pixel, the corresponding plane z-value is subtracted. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. By setting autoAdjustOriginZ true for unsigned integer data, the origin of the result image will be adjusted to avoid clamping at zero. Using automatic origin adjustment on a partial region of the image will not compensate the pixel values outside the region for the new origin, such pixels will appear with an offset in global coordinates. Image world coordinate system handling: The plane is interpreted in world space and subtracted from the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image. Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.
gradient, ramp
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. |
plane |
CONST_OBJECT Shape3D |
The plane to subtract, must be a Shape3D plane. |
region |
CONST_OBJECT Image.PixelRegion |
Region of the image where the plane should be subtracted, default is the full image. An empty region or nil are interpreted as the full image. |
autoAdjustOriginZ |
BOOL |
Flag indicating if the origin of the output image should be adjusted to avoid clamping at zero. Default is false, using the same origin as the input image. |
| Name | Type | Description |
|---|---|---|
resultImage |
OBJECT Image |
The image with the subtracted plane. Nil if an error occurred. |
resultImage = Image.subtractPlane(image, plane, region, autoAdjustOriginZ)
subtractPlaneInplace()
Inplace version of the Image.subtractPlane function which modifies the input image by subtracting the value of a given plane. See base function for full documentation.
gradient, ramp
Image.add, Image.addPlane, Image.renderPlane, Image.subtractPlane
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The source image. This image is overwritten with the result image. |
plane |
CONST_OBJECT Shape3D |
The plane to subtract, must be a Shape3D plane. |
region |
CONST_OBJECT Image.PixelRegion |
Region of the image where the plane should be subtracted, default is the full image. An empty region or nil are interpreted as the full image. |
autoAdjustOriginZ |
BOOL |
Flag indicating if the origin of the output image should be adjusted to avoid clamping at zero. Default is false, using the same origin as the input image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.subtractPlaneInplace(image, plane, region, autoAdjustOriginZ)
subtractProfile()
Returns the image with the profile subtracted from all rows or all columns depending on the dimension argument. The dimension argument is optional and if not provided processing is done row by row. Image world coordinate system handling: The input profile is in world coordinates. The result image will have originZ set to zero. Missing data handling: For missing data in the image, the pixels with missing data will still be zero. For missing data in the profile, the image data will be unchanged. If missing data note that the minimum value is always 1 for valid pixels.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image. |
profile |
CONST_OBJECT Profile |
The profile. |
dimension |
ENUM ProcessingDimension |
Optional processing dimension (row/column). |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Image with profile subtracted along processing dimension. |
result = Image.subtractProfile(image, profile, dimension)
subtractProfileInplace()
Inplace version of the Image.subtractProfile function that modifies the input image. See base function for full documentation.
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image. This image is overwritten with the result image. |
profile |
CONST_OBJECT Profile |
The profile. |
dimension |
ENUM ProcessingDimension |
Optional processing dimension (row/column). |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.subtractProfileInplace(image, profile, dimension)
thin()
Applies a morphological thinning, also known as skeletonization, using the Guo-Hall algorithm. It is typically performed on an already binarized input image. Zeros in the input image are be interpreted as background pixels. Note: The algorithm can be slow for large images with many non-zeros (large binary objects). Consider operating on regions of interest if possible. The output is a binary image with the skeleton indicated by pixels set to the maximum value of the pixel type, e.g., 255 for the uint8 type. Image world coordinate system handling: The image world coordinate system is not considered in this function. The output image inherits the x,y origin and x,y pixelsize, but the z-origin is reset to 0 and z-pixelsize to 1. Missing data handling: The missing data flag is reset by this function as the output is a binary image.
morphology, skeleton
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image, expected to be binary. Supported image types are uint8 and uint16. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the operation is only performed within the bounding box of its region. This can save a lot of computation time, if the region is small. |
| Name | Type | Description |
|---|---|---|
skeletonImage |
OBJECT Image |
Skeleton image. |
skeletonImage = Image.thin(image)
threshold()
Threshold the image by keeping all pixels with a value between lowerThreshold and upperThreshold (inclusive). Return the result as a PixelRegion object. Image world coordinate system handling: The input thresholds are interpreted in the image world coordinate system considering the z-origin and z-pixelsize, e.g., in millimeter scale if the image would represent a range image with z-origin different from 0 of a z-pixelsize different from 1. A conversion is done within the function to raw pixel value thresholds. Missing data handling: Missing data pixels are excluded from the output PixelRegion object.
background, blob, foreground, region, segmentation
Image.binarizeAdaptive, Image.binarizeCompare, Image.binarizePlane, Image.thresholdCompare, Image.thresholdPlane, Image.binarize
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. |
lowerThreshold |
FLOAT |
Lower threshold. Expressed in image world coordinates if applicable. |
upperThreshold |
FLOAT |
Upper threshold. Optional, default is no upper threshold (only include pixels larger than the lower threshold) |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. |
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
Pixel region containing all pixels with value between the thresholds. |
region = Image.threshold(image, 1, 255) -- Gets a region containing all non-zero values of an uint8 image
thresholdCompare()
Threshold an image by pixelwise comparison with a reference image. All pixels with a value greater than or equal to the corresponding reference image value are included in the output PixelRegion object. An optional margin (positive or negative) may be provided, adjusting the reference image values prior to the comparison. A larger positive margin results in fewer included pixels. The optional flag findBright may be set to false, returning the region where the image is lower/darker than the reference image. A region of interest can be provided, limiting the processing to that region. The images must be of the same pixel type and be of equal size. This function gives a PixelRegion objects as output, to get a binary image as output use binarizeCompare instead. Image world coordinate system handling: To allow for an efficient comparison, the z-pixelsizes of the input images must be equal but the z-offsets may differ. The margin parameter is interpreted in image world coordinates, e.g., as a millimeter margin if the input is a range image. Missing data handling: Missing data pixels are excluded from the output PixelRegion object.
adaptive, background, blob, foreground, region, segmentation, binarize
Image.binarize, Image.binarizeAdaptive, Image.binarizeCompare, Image.binarizePlane, Image.thresholdPlane, Image.threshold
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image to threshold. |
referenceImage |
CONST_OBJECT Image |
Reference image to compare the input image with. |
marginWorld |
FLOAT |
Optional margin added to the reference image. Default value is 0. |
findBright |
BOOL |
Optional flag indicating if pixels brighter/higher or darker/lower than the reference image should be included. Default is true, returning brighter pixels. |
regionOfInterest |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. The default region is the entire image. |
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
PixelRegion object containing all pixels passing the comparison operation. |
region = Image.thresholdCompare(image, referenceImage, marginWorld, findBright, regionOfInterest)
thresholdPlane()
Thresholds the image by keeping all pixels with a world value between lowerThreshold and upperThreshold relative to the provided plane (inclusive). Returns the result as a PixelRegion object. Thresholding values strictly below or above the reference plane is also supported, using relative thresholds with the same sign. Image world coordinate system handling: The plane is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. Thresholds are interpreted in the world coordinate system. Missing data handling: No pixel marked as missing is included in the output region.
adaptive, background, blob, foreground, region, segmentation, binarize
Image.binarize, Image.binarizeAdaptive, Image.binarizeCompare, Image.binarizePlane, Image.thresholdCompare, Image.threshold
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image |
lowerThreshold |
FLOAT |
Lower threshold relative to plane. |
upperThreshold |
FLOAT |
Upper threshold relative to plane. |
plane |
CONST_OBJECT Shape3D |
The plane, represented as a Shape3D, to which the lower and upper thresholds are related. The shape type must be a plane. |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the threshold operation is only performed within this region. This can save a lot of computation time, if the region is small. |
| Name | Type | Description |
|---|---|---|
thresholdedRegion |
OBJECT Image.PixelRegion |
Pixel region containing all pixels with value between the thresholds relative to the plane. |
thresholdedRegion = Image.thresholdPlane(image, lowerThreshold, upperThreshold, plane, region)
toGray()
Converts an RGB image into a gray value image.
RGB, grey
| Name | Type | Description |
|---|---|---|
imageRGB |
CONST_OBJECT Image |
RGB image (8-bit) to convert. |
| Name | Type | Description |
|---|---|---|
imageGray |
OBJECT Image |
Gray value image of uint8 pixel type. |
imageGray = Image.toGray(imageRGB)
toHSV()
Converts an RGB image into individual HSV color space components. The Hue-component is usually represented as an angle in the interval [0,360], but to fit in a uint8 image the value is divided by 2 to be in the interval [0,180].
HSL, RGB, hue, saturation, color
| Name | Type | Description |
|---|---|---|
imageRGB |
CONST_OBJECT Image |
RGB image (8-bit) to convert. |
| Name | Type | Description |
|---|---|---|
imageH |
OBJECT Image |
Hue image, uint8 pixel type and in range [0,180] |
imageS |
OBJECT Image |
Saturation image, uint8 pixel type and in range [0,255] |
imageV |
OBJECT Image |
Value image, uint8 pixel type and in range [0,255] |
imageH, imageS, imageV = Image.toHSV(imageRGB)
toLab()
Converts an RGB image into individual Lab color space components.
RGB, color
| Name | Type | Description |
|---|---|---|
imageRGB |
CONST_OBJECT Image |
RGB image (8-bit) to convert. |
| Name | Type | Description |
|---|---|---|
imageL |
OBJECT Image |
Lightness image, uint8 pixel type and in range [0,255] |
imageA |
OBJECT Image |
'a' color component image, uint8 pixel type and in range [1,255] |
imageB |
OBJECT Image |
'b' color component image, uint8 pixel type and in range [1,255] |
imageL, imageA, imageB = Image.toLab(imageRGB)
toMatrix()
Creates a matrix from a monochrome image. Each entry in the matrix corresponds to the pixel value scaled by the image world Z coordinates. Missing data is set to NaN in the matrix.
| Name | Type | Description |
|---|---|---|
inputImage |
CONST_OBJECT Image |
The input image. |
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The matrix with the image content. |
local matrix = Image.toMatrix(inputImage)
toPixelCoordinate()
Converts an image world coordinate to a pixel coordinate.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
|
worldCoordinate |
CONST_OBJECT Point |
The world coordinate point. |
| Name | Type | Description |
|---|---|---|
pixelCoordinate |
OBJECT Point |
Returns the pixel coordinate. |
local pixelCoordinate = Image.toPixelCoordinate(image, worldCoordinate)
toPixelZ()
Converts a z world coordinate value to a raw pixel value using the image world coordinate system supplied by the input reference image. The mapping pixelValue = (worldZCoordinate - originZ)/pixelSizeZ is made.
| Name | Type | Description |
|---|---|---|
refImage |
CONST_OBJECT Image |
Image carrying the image world coordinate system. No other information from the image is used. |
worldZCoordinate |
FLOAT |
World z coordinate(s), e.g., millimeters. |
| Name | Type | Description |
|---|---|---|
pixelValue |
FLOAT |
Raw pixel value(s). |
local pixelValue = Image.toPixelZ(image, worldZCoordinate)
toPointCloud()
Creates a pointcloud from image(s). Typically one heightmap input image is used in which the pixel pitch is constant in each dimension. The alternative use cases are to supply separate images for either x and z or for x, y and z coordinates. In total there are three ways this can be used: 1. Image.toPointCloud(range, true/false, intensity, region) 2. Image.toPointCloud({X, Z}, true/false, intensity, region) 3. Image.toPointCloud({X, Y, Z}, true/false, intensity, region) In case 1 the pixel sizes and origin of the range image is used to create the X and Y coordinates. In case 2 the pixel sizes and origin of of Z is used to create the Y coordinates in the output. In case 3 all positions are uniquely determined by the input images X, Y and Z. Pixel sizes and origin in the input images are unused. The intensity and region inputs are optional and can be used to set the intensity of the output pointcloud and to remove points respectively. Image world coordinate system handling: in general the image world coordinate system is used to create the pointcloud, i.e. the (x, y, z)-pixel sizes and origins are used to create the (x, y, z)-components of the pointcloud. For details see the longer text above. Missing data handling: For images with missing data it is possible to select to keep or remove the missing points. If missing points are kept they are marked as such in the pointcloud and will be black in intensity. If they are removed the grid structure of the image is lost and the point cloud will be considered an unordered point cloud.
extrude
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The source image(s) with range/depth information. Either one range image or 3 coordinate images (X, Y and Z). |
removeMissing |
BOOL |
Select if points that are missing data should be removed or not. For images without missing data this has no effect. Default is false. |
intensity |
CONST_OBJECT Image |
Optional uint8 image that will be used for intensity information for each point. The pixel values are divided by 255 to create a number in the range [0,1] for the pointcloud intensity. |
region |
CONST_OBJECT Image.PixelRegion |
Optional PixelRegion. If supplied, only points within the region are converted. |
| Name | Type | Description |
|---|---|---|
pointcloud |
OBJECT PointCloud |
The resulting pointcloud. |
local pointcloud = Image.toPointCloud(image, removeMissing, intensity, region)
toRGB()
Creates an RGB image from three grayscale images. The input images must be of uint8 type.
color
| Name | Type | Description |
|---|---|---|
imageR |
CONST_OBJECT Image |
Gray value image of uint8 type. |
imageG |
CONST_OBJECT Image |
Gray value image of uint8 type. |
imageB |
CONST_OBJECT Image |
Gray value image of uint8 type. |
colorSpace |
ENUM ColorSpace |
The color space the input images represent. |
| Name | Type | Description |
|---|---|---|
imageRGB |
OBJECT Image |
RGB image (8-bit). |
imageRGB = Image.toRGB(imageR, imageG, imageB, colorSpace)
toSquarePixels()
Resizes an image to have square pixels, i.e., to have equal pixelsizes in the x and y dimensions. Having square pixels is sometimes required for further processing. Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, will be copied directly from the input image. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
resample, scale, transform, anisotropic
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image |
upsample |
BOOL |
Select if to upsample one axis or downsample the other. Default is false. |
method |
ENUM InterpolationMethod |
The resampling method. Default is LINEAR. |
| Name | Type | Description |
|---|---|---|
squarePixelImage |
OBJECT Image |
Image with square pixels. |
squarePixelImage = Image.toSquarePixels(image)
toString()
Gets a user-friendly string description of the image, containing all properties but no actual pixel values.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to describe. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the image. |
str = Image.toString(image)
toType()
Converts an image to a new image of specified pixel type. The raw pixel values are casted and there may be underflow/overflow effects when casting to a type of lower capacity. For example, the value 256 in a uint16 image will overflow to 0 if converted to a uint8 type. To avoid such effects, clamp the input pixel values to the min and max values of the target pixel type. Supports only monochrome image types, for the RGB24 type there are more specific conversion functions toGray() and toRGB().
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image to be converted. |
type |
ENUM ImageType |
The pixel type, e.g., UINT8, INT16, FLOAT64). |
| Name | Type | Description |
|---|---|---|
convertedImage |
OBJECT Image |
Returns the image of specified type or nil. |
local convertedImage = Image.toType(image, "UINT8")
toWorldCoordinate()
Converts a pixel coordinate to an image world coordinate.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
The image |
pixelCoordinate |
CONST_OBJECT Point |
The pixel coordinate point. |
| Name | Type | Description |
|---|---|---|
worldCoordinate |
OBJECT Point |
Returns the world coordinate. |
local worldCoordinate = Image.toWorldCoordinate(image, pixelCoordinate)
toWorldZ()
Converts a pixel raw value to a z world coordinate value using the image world coordinate system supplied by the input reference image. The mapping worldZCoordinate = pixelValue*pixelSizeZ + originZ is made.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Image carrying the image world coordinate system. No other information from the image is used. |
pixelValue |
FLOAT |
Raw pixel value(s). |
| Name | Type | Description |
|---|---|---|
worldZCoordinate |
FLOAT |
World z coordinate(s), e.g., millimeters. |
local worldZCoordinate = Image.toWorldZ(image, pixelValue)
transform()
Applies a linear geometric transform to an image. The result image uses the same pixel grid as the input image, if the SAME output grid is selected. Image world coordinate system handling: If the image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the input image and the transformed image is by default (output grid SAME) repainted onto this coordinate system. Using output grid FULL, the output image size and origin is set to fit the entire output. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
linear, rotate, scale, shear, shift, warp
Image.Calibration.Correction, Image.crop, Image.cropRectify, Image.resize, Image.resizeFactor, Image.rotate, Image.warpSector, Image.transformInto
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. |
transform |
CONST_OBJECT Transform |
A linear transform defined by a Transform object. |
method |
ENUM InterpolationMethod |
The resampling method. Default is NEAREST. |
grid |
ENUM OutputGrid |
The pixel grid to use for the output, default is SAME, the same as the input image. |
| Name | Type | Description |
|---|---|---|
transformedImage |
OBJECT Image |
Transformed image. |
transformedImage = Image.transform(image, transform, method)
transformInto()
Applies a linear geometric transform to an image and writes the result into the pixel grid defined by the destination image. The pixel grid and coordinate system of the destination image is used for transform operation. Compared to the Image.transform function, this function gives a higher degree of control over the following parameters: - The size of the output image - The pixel sizes of the output image - The world origin of the output image All the above properties are set by the input destination image. For example, a unit transform where the destination image has a world coordinate system different from the input image will resample the image. Image world coordinate system handling: If the image or destination image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is kept in the destination image and the transformed image is painted onto this coordinate system. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image. The missing data flags of the input and destination images must match.
linear, rotate, scale, shear, shift, warp
Image.Calibration.Correction, Image.crop, Image.cropRectify, Image.resize, Image.resizeFactor, Image.rotate, Image.warpSector, Image.transform
| Name | Type | Description |
|---|---|---|
sourceImage |
CONST_OBJECT Image |
Source image. |
transform |
CONST_OBJECT Transform |
A linear transform defined by a Transform object. |
destinationImage |
OBJECT Image |
Destination image, the output will be placed into this image. The image size, pixels sizes and world origin from this image are used. |
method |
ENUM InterpolationMethod |
The resampling method. Default is NEAREST. |
| Name | Type | Description |
|---|---|---|
transformedImage |
OBJECT Image |
A reference to the input destinationImage. Nil on failure. |
transformedImage = Image.transformInto(sourceImage, transform, destinationImage, method)
transformInto3D()
Applies a 3D linear geometric transform to an image and writes the result into the pixel grid defined by the destination image. Compared to the transformInto function, this function adds the possibility for 3D tilts. The function is typically used for heightmap image data. The pixel grid and coordinate system of the destination image are used for the transform operation. Compared to the Image.transform function, this function gives a higher degree of control over the following parameters: - The size of the output image - The pixel sizes of the output image - The world origin of the output image All the above properties are set by the input destination image. For example, a unit transform where the destination image has a world coordinate system different from the input image will resample the image. Image world coordinate system handling: If the image or reference image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the reference image and the transformed image is repainted onto this coordinate system. Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.
linear, rotate, scale, shear, shift, warp
Image.Calibration.Correction, Image.crop, Image.resize, Image.resizeFactor, Image.rotate, Image.transformInto, Image.warpSector, Image.transform
| Name | Type | Description |
|---|---|---|
sourceImage |
CONST_OBJECT Image |
Source image. |
transform |
CONST_OBJECT Transform |
A linear affine 3D transform defined by a Transform object. |
destinationImage |
OBJECT Image |
Destination image, the output will be placed into this image. The image size, pixels sizes and world origin from this image are used. |
method |
ENUM InterpolationMethod |
The resampling method. Default is NEAREST. |
splatX |
INT |
The influence distance of a source point in the target image x direction. Default is 3. |
splatY |
INT |
The influence distance of a source point in the target image y direction. Defaults to splatX if unset. |
clearTarget |
BOOL |
Select if the destinationImage should be reset to missing data before transforming the source image into it. |
| Name | Type | Description |
|---|---|---|
transformedImage |
OBJECT Image |
A reference to the input destinationImage. Nil on failure. |
transformedImage = Image.transformInto3D(sourceImage, transform, destinationImage, method)
warpSector()
Warps the inner area of a sector shape to a rectilinear Cartesian grid.
rectify, unwrap
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image. |
sector |
CONST_OBJECT Shape |
A sector shape defining the area in the source image to warp from. |
interpolation |
ENUM InterpolationMethod |
Interpolation method to use. Currently only LINEAR is available. |
| Name | Type | Description |
|---|---|---|
warpedImage |
OBJECT Image |
The warped image, or nil on failure. |
warpedImage = Image.warpSector(image, sector, interpolation)
Image.Calibration
Overview
Image.Calibration.CameraModel
Calibration result object of single camera. These objects can be stored to and loaded from file. The results of the camera calibration satisfy the camera transformation equation from world to the image coordinate system: xp = KD([R|t] * X) K = [fx s cx, 0 fy cy, 0 0 1] D = Brown–Conrady lens model: k1, k2, p1, p2, k3 R = [r11 r12 r13, r21 r22 r23, r31 r32 r33] t = [tx ty tz]^T
Overview
create(), getCalibrationImageSize(), getCameraID(), getEulerAngles(), getFocalDistance(), getIntrinsicK(), getPosition(), getProjectionMatrix(), getSensorToWorldDistortion(), getTransform(), getWorldToSensorDistortion(), getXMLVersionTag(), load(), save(), setCalibrationImageSize(), setCameraID(), setFocalDistance(), setIntrinsicK(), setProjectionMatrix(), setSensorToWorldDistortion(), setTransform(), setWorldToSensorDistortion(), toString()
Functions
create()
Create a instance for the calibration result handling
| Name | Type | Description |
|---|---|---|
cameraModel |
The calibration result object instance. |
cameraModel = Image.Calibration.CameraModel.create()
getCalibrationImageSize()
Get the image size for which the calibration is valid.
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
imageWidth |
INT |
The image width for which the calibration is valid. |
imageHeight |
INT |
The image height for which the calibration is valid. |
local imageWidth, imageHeight = Image.Calibration.CameraModel.getCalibrationImageSize(cameraModel)
getCameraID()
Get the unique camera identifier.
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
cameraID |
STRING |
The unique camera identifier. |
local cameraID = Image.Calibration.CameraModel.getCameraID(cameraModel)
getEulerAngles()
Get the Euler angle representation (yaw, pitch, roll) of the transform into camera coordinates (in degree).
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
yaw |
FLOAT |
The rotation around x-axis in degree. |
pitch |
FLOAT |
The rotation around y-axis in degree. |
roll |
FLOAT |
The rotation around z-axis in degree. |
local yaw, pitch, roll = Image.Calibration.CameraModel.getEulerAngles(cameraModel)
getFocalDistance()
Get the camera model focus setting parameter.
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
focalDistance |
FLOAT |
Distance from the camera to the plane of best image sharpness. |
unit |
STRING |
Focal distance unit. Default is mm. |
local focalDistance, unit = Image.Calibration.CameraModel.getFocalDistance(cameraModel)
getIntrinsicK()
Get the intrinsic camera matrix.
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
intrinsic |
OBJECT Matrix |
A 3x3 matrix with the intrinsic camera parameters: K = [fx s cx, 0 fy cy, 0 0 1] |
local intrinsic = Image.Calibration.CameraModel.getIntrinsicK(cameraModel)
getPosition()
Returns the position of the camera center as a 3D Point. If no extrinsic calibration is available the position will be in origin (0, 0, 0).
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
center |
OBJECT Point |
Camera center world position as a 3D point. |
local center = Image.Calibration.CameraModel.getPosition(cameraModel)
getProjectionMatrix()
Get the 3x4 projection matrix P = K[R|t]. Transformation xp = K*(R*Xw + T), with xp = [u/z, v/z, z/z] = [x,y,1] in homogeneous coordinates and Xw = [X,Y,Z] in 3D world coordinates.
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
projectionMatrix |
OBJECT Matrix |
A 3x4 projection matrix P = K[R |
local projectionMatrix = Image.Calibration.CameraModel.getProjectionMatrix(cameraModel)
getSensorToWorldDistortion()
Get the lens distortion coefficients [k1, k2, p1, p2, k3].
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
k1 |
FLOAT |
Second order radial lens distortion coefficient. |
k2 |
FLOAT |
Fourth order radial lens distortion coefficient. |
p1 |
FLOAT |
First tangential lens distortion coefficient. |
p2 |
FLOAT |
Second tangential lens distortion coefficient. |
k3 |
FLOAT |
Sixth order radial lens distortion coefficient. |
local k1, k2, p1, p2, k3 = Image.Calibration.CameraModel.getSensorToWorldDistortion(cameraModel)
getTransform()
Returns the pose of the camera as Transform object.
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
transform |
OBJECT Transform |
Rigid transformation from world to camera coordinates [R,t]. |
local transform = Image.Calibration.CameraModel.getTransform(cameraModel)
getWorldToSensorDistortion()
Get the lens distortion coefficients [k1, k2, p1, p2, k3].
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
k1 |
FLOAT |
Second order radial lens distortion coefficient. |
k2 |
FLOAT |
Fourth order radial lens distortion coefficient. |
p1 |
FLOAT |
First tangential lens distortion coefficient. |
p2 |
FLOAT |
Second tangential lens distortion coefficient. |
k3 |
FLOAT |
Sixth order radial lens distortion coefficient. |
local k1, k2, p1, p2, k3 = Image.Calibration.CameraModel.getWorldToSensorDistortion(cameraModel)
getXMLVersionTag()
Get the version tag of the XML file.
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
| Name | Type | Description |
|---|---|---|
versionTag |
STRING |
The version tag of the XML. |
local versionTag = Image.Calibration.CameraModel.getXMLVersionTag(cameraModel)
load()
Load calibration result object from a file. This function is deprecated, please use Object.save/load instead.
| Name | Type | Description |
|---|---|---|
fileName |
STRING |
Filename, including path and file extension. |
| Name | Type | Description |
|---|---|---|
cameraModel |
The calibration result object or nil |
local cameraModel = Image.Calibration.CameraModel.load("private/CalibrationResult.xml)
save()
Save calibration result object to a file. This function is deprecated, please use Object.save/load instead.
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The instance to use. |
fileName |
STRING |
Filename, including path and file extension. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if the file is written correctly. |
local success = Image.Calibration.CameraModel.save(cameraModel, "private/CalibrationResult.xml")
setCalibrationImageSize()
Set the image size for which the calibration is valid.
| Name | Type | Description |
|---|---|---|
cameraModel |
The instance to use. |
|
imageWidth |
INT |
The image width for which the calibration is valid. |
imageHeight |
INT |
The image height for which the calibration is valid. |
Image.Calibration.CameraModel.setCalibrationImageSize(cameraModel, imageWidth, imageHeight)
setCameraID()
Set the unique camera identifier.
| Name | Type | Description |
|---|---|---|
cameraModel |
The instance to use. |
|
cameraID |
STRING |
The unique camera identifier. |
Image.Calibration.CameraModel.setCameraID(cameraModel, cameraID)
setFocalDistance()
Set the camera model focus setting parameter.
| Name | Type | Description |
|---|---|---|
cameraModel |
The instance to use. |
|
focalDistance |
FLOAT |
Distance from the camera to the plane of best image sharpness. |
unit |
STRING |
Focal distance unit. Default is mm. |
Image.Calibration.CameraModel.setFocalDistance(cameraModel, focalDistance, unit)
setIntrinsicK()
Set the intrinsic camera matrix.
| Name | Type | Description |
|---|---|---|
cameraModel |
The instance to use. |
|
intrinsic |
OBJECT Matrix |
A 3x3 matrix with the intrinsic camera parameters: K = [fx s cx, 0 fy cy, 0 0 1] |
Image.Calibration.CameraModel.setIntrinsicK(cameraModel, intrinsic)
setProjectionMatrix()
Set the 3x4 projection matrix P = K[R|t].
| Name | Type | Description |
|---|---|---|
cameraModel |
The instance to use. |
|
projectionMatrix |
OBJECT Matrix |
A 3x4 projection matrix P = K[R |
Image.Calibration.CameraModel.setProjectionMatrix(cameraModel, projectionMatrix)
setSensorToWorldDistortion()
Set the lens distortion coefficients [k1, k2, p1, p2, k3].
| Name | Type | Description |
|---|---|---|
cameraModel |
The instance to use. |
|
k1 |
FLOAT |
Set second order radial lens distortion coefficient. |
k2 |
FLOAT |
Set fourth order radial lens distortion coefficient. |
p1 |
FLOAT |
Set first tangential lens distortion coefficient. |
p2 |
FLOAT |
Set second tangential lens distortion coefficient. |
k3 |
FLOAT |
Set sixth order radial lens distortion coefficient. |
local transform = Image.Calibration.CameraModel.setSensorToWorldDistortion(cameraModel, k1, k2, p1, p2, k3)
setTransform()
Set the pose transformation of the camera as Transform object.
| Name | Type | Description |
|---|---|---|
cameraModel |
The instance to use. |
|
transform |
OBJECT Transform |
Rigid transformation describing the transformation from world to camera coordinates [R,t]. |
local transform = Image.Calibration.CameraModel.setTransform(cameraModel, transform)
setWorldToSensorDistortion()
Set the lens distortion coefficients [k1, k2, p1, p2, k3].
| Name | Type | Description |
|---|---|---|
cameraModel |
The instance to use. |
|
k1 |
FLOAT |
Set second order radial lens distortion coefficient. |
k2 |
FLOAT |
Set fourth order radial lens distortion coefficient. |
p1 |
FLOAT |
Set first tangential lens distortion coefficient. |
p2 |
FLOAT |
Set second tangential lens distortion coefficient. |
k3 |
FLOAT |
Set sixth order radial lens distortion coefficient. |
local transform = Image.Calibration.CameraModel.setWorldToSensorDistortion(cameraModel, k1, k2, p1, p2, k3)
toString()
Gets a short string description of the camera model.
| Name | Type | Description |
|---|---|---|
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
The camera model object. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
Description of the camera model. |
local str = Image.Calibration.CameraModel.toString(cameraModel)
Image.Calibration.Correction
Correction of image distortions based on a calibrated camera model. Supports correction of lens distortion and perspective distortion from small tilt angles and image rotations.
Keywords
distortion, lens, perspective, rectification, rectify, untilt, unwarp, undistort
See also
Overview
Functions
apply()
Apply the image correction to an input image.
| Name | Type | Description |
|---|---|---|
corr |
HANDLE |
The correction object to use. |
inputImage |
CONST_OBJECT Image |
Input image |
| Name | Type | Description |
|---|---|---|
outputImage |
OBJECT Image |
Output image. |
outputImage = corr:apply(inputImage)
create()
Create an image correction object.
Image.Calibration.Correction.setAlignMode, Image.Calibration.Correction.setUntiltMode, Image.Calibration.Correction.setUndistortMode
| Name | Type | Description |
|---|---|---|
corr |
HANDLE |
corr = Image.Calibration.Correction.create()
getValidRegion()
Get a pixel region corresponding to the valid part of the corrected image. The valid part of the output image contains pixel values from the input image, and the invalid part is just set to zero.
| Name | Type | Description |
|---|---|---|
corr |
HANDLE |
The correction object to use. |
| Name | Type | Description |
|---|---|---|
validRegion |
OBJECT Image.PixelRegion |
Valid region of the output. |
validRegion = corr:getValidRegion()
getVirtualCamera()
Get a camera model representing the virtual camera producing the corrected image.
| Name | Type | Description |
|---|---|---|
corr |
HANDLE |
The correction object to use. |
| Name | Type | Description |
|---|---|---|
camera |
Virtual camera of the correction procedure. |
camera = corr:getVirtualCamera()
mapPoints()
Map points between the four coordinate systems related to the correction process. See the CoordinateSystem enum for details.
| Name | Type | Description |
|---|---|---|
corr |
HANDLE |
The correction object to use. |
pointsIn |
OBJECT Point |
Points to transform (single point or array). |
sourceSystem |
ENUM CoordinateSystem |
Specifies the coordinate system in which the input point is defined. |
targetSystem |
ENUM CoordinateSystem |
Specifies the coordinate system to transform the points into. |
| Name | Type | Description |
|---|---|---|
pointsOut |
OBJECT Point |
Transformed points (single point or array). |
pointsOut = corr:mapPoints(pointsIn, sourceSystem, targetSystem)
setAlignMode()
Setup the correction to map specific world ground plane rectangle to an image. This gives precise control of the pixel size and world origin of the output image.
| Name | Type | Description |
|---|---|---|
corr |
HANDLE |
The correction object to setup. |
cameraModel |
A model of a calibrated camera, as returned from the Image.Calibration functions. |
|
worldRect |
CONST_OBJECT Shape |
World rectangle describing the world region to cover. |
pixelSize |
FLOAT |
Desired pixel size (mm/pixel) of the output image. If omitted, a similar pixel size as in the input image center will be used. |
interpolation |
ENUM InterpolationMethod |
Interpolation method to use. Default is LINEAR. |
corr:setAlignMode(cameraModel, worldRect, pixelSize, interpolation)
setUndistortMode()
Setup the correction to compensate for lens distortion only. The other parts of the camera model are ignored.
| Name | Type | Description |
|---|---|---|
corr |
HANDLE |
The correction object to setup. |
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
A model of a calibrated camera, as returned from the Image.Calibration functions. |
cropMode |
ENUM CorrectionCropMode |
Crop mode, determines how to crop the output. Default is FULL. |
interpolation |
ENUM InterpolationMethod |
Interpolation method to use. Default is LINEAR. |
corr:setUndistortMode(cameraModel, cropMode, interpolation)
setUntiltMode()
Setup the correction to compensate for lens distortion and perspective distortions caused by a tilt angle between the world ground plane and the camera. Any in-plane rotation between the camera and world is left unaltered.
| Name | Type | Description |
|---|---|---|
corr |
HANDLE |
The correction object to setup. |
cameraModel |
CONST_OBJECT Image.Calibration.CameraModel |
A model of a calibrated camera, as returned from the Image.Calibration functions. |
cropMode |
ENUM CorrectionCropMode |
Crop mode, determines how to crop the output. Default is FULL. |
interpolation |
ENUM InterpolationMethod |
Interpolation method to use. Default is LINEAR. |
targetWidth |
INT |
Output image width. Default is same size as the input. |
targetHeight |
INT |
Output image height. Default is same size as the input. |
corr:setUntiltMode(cameraModel, pixelSize, origin)
Image.Fixture
Helper object for transformation of geometrical primitives between different views of the same object. This object is typically used in a locate-inspect concept, where a teach image is used to define a set of measurement tasks. These measurement tasks will then be executed on a set of live images, where the object to measure may be translated, rotated and/or scaled differently than in the teach image. Typically, the following steps are included in locate-inspect applications: - Teach a matching algorithm (EdgeMatcher, PointMatcher, PatternMatcher) from a teach image. Use the teach pose returned from the teach procedure as reference pose for the fixture. - Define a set of points or shapes in the teach image, related to various measurement tasks. Append these to the fixture using the append functions. - For each live image, find the object using a match call of the selected matching algorithm. Transform the fixture to this new object pose using Fixture.transform. - Get the transformed points or shapes using the get functions, now relating to the found pose of the object in the live image. Saving and loading a fixture: A Image.Fixture instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.
Keywords
local, object, reference, coordinate system
Overview
Functions
appendAngle()
Append an angle to the fixture.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the angle, used when retrieving the angle later on. |
angle |
FLOAT |
Angle to append. |
Image.Fixture.appendAngle(fixture, "angle1", 3.1415/2)
appendPoint()
Append a point to the fixture.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the point, used when retrieving the point later on. |
point |
CONST_OBJECT Point |
Point to append. |
Image.Fixture.appendPoint(fixture, "point1", point)
appendPose()
Append a pose transform to the fixture. Typically, the appended pose defines the pose of an object part. For example, the pose returned from the PatternVerifier teach method can be appended to a fixture. After calling Fixture.transform() to transform the fixture to a live image, Fixture.getPose() will give the pose of the part in the live image. The output from getPose can then be used in a call to PatternVerifier.verify() to verify the part in the live image.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the pose, used when retrieving the pose later on. |
pose |
CONST_OBJECT Transform |
Pose to append, defined in image world coordinates. |
Image.Fixture.appendPose(fixture, "pose1", pose)
appendShape()
Append a shape or composite shape to the fixture.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the shape, used when retrieving the shape later on. |
shape |
CONST_OBJECT Shape |
Shape or composite shape to append. |
Image.Fixture.appendShape(fixture, "shape1", shape)
create()
Create a new fixture.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
The new fixture. |
fixture = Image.Fixture.create()
getAngle()
Get an angle from the fixture, transformed according to the current fixture transform.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the angle to retrieve. |
| Name | Type | Description |
|---|---|---|
angle |
FLOAT |
The retrieved angle. |
angle = Image.Fixture.getAngle(fixture, "angle1")
getAsPixelRegion()
Get a shape or composite shape region from the fixture, transformed directly to a pixel region for use as algorithm input. Since the returned object is not a shape, more general transformations are supported by this function compared to getShape().
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the shape or composite shape to retrieve. |
referenceImage |
CONST_OBJECT Image |
Reference image, use to determine the pixel-world mapping. |
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
The transformed shape, converted to a pixel region. |
region = Image.Fixture.getAsPixelRegion(fixture, "shape1", referenceImage)
getPoint()
Get a point from the fixture, transformed according to the current fixture transform.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the point to retrieve. |
| Name | Type | Description |
|---|---|---|
point |
OBJECT Point |
The retrieved point. |
point = Image.Fixture.getPoint(fixture, "point1")
getPose()
Get a pose from the fixture, transformed according to the current fixture transform. Typically, this is used to get the pose of an object part. For example, the pose returned from getPose can be used as input to the PatternVerifier match function. See appendPose for more information.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the pose to retrieve. |
| Name | Type | Description |
|---|---|---|
pose |
OBJECT Transform |
The retrieved pose. |
pose = Image.Fixture.getPose(fixture, "pose1")
getShape()
Get a shape or composite shape from the fixture, transformed according to the current fixture transform. Nil is returned if the shape can not be transformed accordingly.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the object to retrieve. |
| Name | Type | Description |
|---|---|---|
shape |
AUTO |
The retrieved shape or composite shape. |
shape = Image.Fixture.getShape(fixture, "shape1")
setReferencePose()
Set the reference pose of this fixture. This defines the object pose that all geometrical items will be related to. Typically, the teachPose output from the teach function of a matching tool (for example Image.Matching.EdgeMatcher.teach()) is used as input to this function.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
referencePose |
CONST_OBJECT Transform |
Pose transform of the object that all appended geometrical items will be related to. |
Image.Fixture.setReferencePose(fixture, referencePose)
toString()
Get a user-friendly string description of the fixture.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
| Name | Type | Description |
|---|---|---|
description |
STRING |
User-friendly description of the fixture. |
local description = Image.Fixture.toString(fixture)
transform()
Transform the fixture to a new pose. This will affect the pose of all geometrical items retrieved using the get functions. Typically, the pose transform output from the match function of a matching tool (for example Image.Matching.EdgeMatcher.match()) is often used as input to this function.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
poseTransform |
CONST_OBJECT Transform |
Pose transform of the new fixture pose. |
Image.Fixture.transform(fixture, poseTransform)
Image.Fixture3D
Helper object for transformation of 3D geometrical primitives (Shapes, Points, regions). This object is typically used in a locate-inspect concept together with the EdgeMatcher3D, where a teach image is used to define a set of measurement tasks. These measurement tasks will then be executed on a set of live images, where the object to measure may be translated, rotated and/or scaled differently than in the teach image. The shadow region of a shape on the z=0 plane can be obtained directly using getAsPixelRegion. This function also allows more general transforms compared to the getShape function. E.g. using getPose on a circle will only allow up to similarity transforms, while getAsPixelRegion allows homography transforms. Typically, the following steps are included in locate-inspect applications: - Teach a 3D matching algorithm such as EdgeMatcher3D using a teach image. Use the teach pose returned from the teach procedure as reference pose for the fixture. - Define a set of points or shapes in the teach image, related to various measurement tasks. Append these to the fixture using the append functions. - For each live image, find the object using a match call of the selected matching algorithm. Transform the fixture to this new object pose using Fixture3D.transform(). - Get the transformed points or shapes using the get functions, now relating to the found pose of the object in the live image. Saving and loading a fixture: A Image.Fixture3D instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.
Keywords
local, object, reference, coordinate system
See also
Overview
Functions
appendPoint()
Appends a 3D point to the fixture.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the point, used when retrieving the point later on. |
point |
CONST_OBJECT Point |
3D point to append. |
Image.Fixture3D.appendPoint(fixture, "point1", point)
appendPose()
Appends a pose transform (Transform 3D object) to the fixture. Typically, the appended pose defines the pose of an object part, for example, the pose returned from teaching 3D matchers for sub-components. After calling Fixture3D.transform() to transform the fixture to a live image, Fixture3D.getPose() will give the pose of the part in the live image.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the pose, used when retrieving the pose later on. |
pose |
CONST_OBJECT Transform |
Transform pose (3D Transform) to append, defined in image world coordinates. |
Image.Fixture3D.appendPose(fixture, "pose1", pose)
appendShape()
Appends a Shape3D object to the fixture.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the shape, used when retrieving the shape later on. |
shape |
CONST_OBJECT Shape3D |
Shape3D object to append. |
Image.Fixture3D.appendShape(fixture, "shape1", shape)
create()
Creates a new 3D fixture.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
The new fixture. |
fixture = Image.Fixture3D.create()
getAsPixelRegion()
Gets a 3D shape from the fixture represented as a pixel region plus height boundaries (zMin, zMax). The pixel region is the convex hull of the shape projected onto the plane z = 0. More general transforms are allowed when using getAsPixelRegion, even transforms that changes the type of shape.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the shape to retrieve. |
referenceImage |
CONST_OBJECT Image |
Reference image, used to supply the image world coordinate system. |
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
The transformed shape, converted to a pixel region. |
zMin |
FLOAT |
The lowest z-value encountered in the shape after transformation but before projection. |
zMax |
FLOAT |
The highest z-value encountered in the shape after transformation but before projection. |
region = Image.Fixture3D.getAsPixelRegion(fixture, "shape1", referenceImage)
getPoint()
Gets a point from the fixture, transformed according to the current fixture transform.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the point to retrieve. |
| Name | Type | Description |
|---|---|---|
point |
OBJECT Point |
The retrieved 3D point. |
point = Image.Fixture3D.getPoint(fixture, "point1")
getPose()
Gets a pose from the fixture, transformed according to the current fixture transform. Typically, this is used to get the pose of an object part.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the pose to retrieve. |
| Name | Type | Description |
|---|---|---|
pose |
OBJECT Transform |
The retrieved pose transform (Transform 3D). |
pose = Image.Fixture3D.getPose(fixture, "pose1")
getShape()
Gets a shape from the fixture, transformed according to the current fixture transform.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
name |
STRING |
Name of the shape to retrieve. |
| Name | Type | Description |
|---|---|---|
shape |
OBJECT Shape3D |
The retrieved 3D shape. |
shape = Image.Fixture3D.getShape(fixture, "shape1")
setReferencePose()
Sets the reference pose of this fixture. This defines the object pose that all geometrical items will be related to. Typically, the teachPose output from the teach function of a matching tool, e.g., EdgeMatcher3D, is used as input to this function.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
referencePose |
CONST_OBJECT Transform |
Pose transform (Transform3D) of the object that all appended geometrical items will be related to. |
Image.Fixture3D.setReferencePose(fixture, referencePose)
toString()
Gets a user-friendly string description of the fixture.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
| Name | Type | Description |
|---|---|---|
description |
STRING |
User-friendly description of the fixture. |
local description = Image.Fixture3D.toString(fixture)
transform()
Transforms the fixture to a new pose. This will affect the pose of all geometrical items retrieved using the get functions. Typically, the pose transform output from the match function of a matching tool is often used as input to this function.
| Name | Type | Description |
|---|---|---|
fixture |
HANDLE |
Fixture object. |
poseTransform |
CONST_OBJECT Transform |
Pose transform (Transform 3D object) of the new fixture pose. |
Image.Fixture3D.transform(fixture, poseTransform)
Image.Format
Image file formats/encodings.
Overview
Image.Format.BMP
BMP encoding functionality
See also
Functions
create()
Creates a new instance of the BMP encoder.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the instance. |
local handle = Image.Format.BMP.create()
decode()
Create an Image object from a binary buffer containing a BMP encoded image.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the BMP instance |
bmpBuffer |
BINARY |
Binary buffer containing the BMP encoded image |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
Decoded image or nil |
local image = Image.Format.BMP.decode(handle, bmpBuffer)
encode()
Create a binary buffer with the BMP encoded image data. Supported image types: UINT8, RGB24
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the instance |
imageIn |
CONST_OBJECT Image |
image to encode |
| Name | Type | Description |
|---|---|---|
bmpBuffer |
BINARY |
binary buffer containing the BMP encoded image or nil |
local bmpBuffer = Image.Format.BMP.encode(handle, image)
Image.Format.JPEG
JPEG encoding functionality
See also
Overview
Functions
create()
Creates a new instance of the JPEG encoder. Default quality level is 50.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance if available. Can be nil if unavailable. |
local handle = Image.Format.JPEG.create()
decode()
Create an Image object from a binary buffer containing a JPEG encoded image.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the JPEG instance |
jpegBuffer |
BINARY |
Binary buffer containing the JPEG encoded image |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
Decoded image or nil |
local image = Image.Format.JPEG.decode(handle, jpegBuffer)
encode()
Create a binary buffer with the JPEG encoded image data.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the JPEG instance |
imageIn |
CONST_OBJECT Image |
Image to encode |
| Name | Type | Description |
|---|---|---|
jpegBuffer |
BINARY |
Binary buffer containing the JPEG encoded image or nil |
local jpegBuffer = Image.Format.JPEG.encode(handle, image)
setQuality()
Configure the JPEG encoding quality, a lower value results in higher compression.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the JPEG instance |
quality |
INT |
The minimum/maximum values depend on the underlying implementation. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successful, false otherwise |
local success = Image.Format.JPEG.setQuality(handle, 50)
Image.Format.PNG
PNG encoding functionality
See also
Overview
Functions
create()
Creates a new instance of the PNG encoder.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the instance. |
local handle = Image.Format.PNG.create()
decode()
Create an Image object from a binary buffer containing a PNG encoded image.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the PNG instance |
pngBuffer |
BINARY |
Binary buffer containing the PNG encoded image |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
Decoded image or nil |
local image = Image.Format.PNG.decode(handle, pngBuffer)
encode()
Create a binary buffer with the PNG encoded image data. Supported image types: UINT8, UINT16, RGB24
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the instance |
imageIn |
CONST_OBJECT Image |
image to encode |
| Name | Type | Description |
|---|---|---|
pngBuffer |
BINARY |
binary buffer containing the PNG encoded image or nil |
local pngBuffer = Image.Format.PNG.encode(handle, image)
setCompression()
Configure the PNG encoding compression (0-9), a higher value results in higher compression and higher run time.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the PNG instance |
compression |
INT |
Ranges from 0 (no compression) to 9 (high compression). Default: 6. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successful, false otherwise |
local success = Image.Format.PNG.setCompression(handle, 1)
Image.Matching
Functions for matching and locating objects and patterns in images based on different object models, including edge-based models, interest point models and pixel pattern models.
Image.Matching.EdgeMatcher
Object matching of objects which are well defined by clean edges/contours in a 2D image. An alternative to the EdgeMatcher is the PointMatcher for objects whose appearance is rather described by a texture pattern. Teach an object model from a reference image and call match to find the location of the same object in a new image. The EdgeMatcher searches for translation, rotation and scale (range 80% - 120%) of objects. Results are given as pose transforms which describe how the object model is transformed to matched positions in the new image. Each match gets a score between 0.0 and 1.0 where 1.0 means a perfect match. The EdgeMatcher is often used together with the Image.Fixture object that facilitates local coordinate transforms based on the result of the EdgeMatcher. The most important parameters for the EdgeMatcher are the following: - Edge threshold: Make sure to select an edge strength threshold that includes the edges of the reference object but excludes clutter edges in the background. Use the getModelContours() function to graphically verify the object model obtained. - Background clutter: If the images contain other patterns and structures other than the object of interest, use the HIGH setting in setBackgroundClutter() which is the default. If the object is on a clean background one can gain speed by setting the background clutter flag to MEDIUM or LOW. There is an interaction with the background clutter setting and the downsample factor parameter below though: It can be possible to run with higher downsample factors using the HIGH background clutter and thus gain higher speed compared to runnning a MEDIUM background clutter and a lower downsample factor. - Downsample factor: The EdgeMatcher works internally on downsampled images for computational performance reasons. The downsample factor is the most important parameter for the speed versus robustness trade-off. A initial choice of downsample factor could be one that generates a downsampled image of size about 200 x 200. For example, if images of size 1024 x 1024 are used, one could start experimenting with a downsample factor of 5. The downsample factor has an effect on the robustness of the algorithm (finding the correct match) but not on the position accuracy. - Rotation range: The rotation range parameter should be selected to be as narrow as possible both for computational reasons and for robustness reasons. If it is known that the target object only can appear within a certain rotation interval relative to the teach pose, make sure to reduce the rotation range search parameter. - Scale range: As with the rotation range parameter, set the scale range as narrowly as possible for computational and performance reasons. Pixel types: The EdgeMatcher accepts uint8 and uint16 pixel type images. Hardware acceleration: Some devices have FPGA-support for the EdgeMatcher. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. If there is FPGA support it is set as default, but note that the FPGA is not able to support all configurations, mainly there is a lower restriction on the downsample factor for memory limitation reasons. There is typically only one instance of the FPGA calculation unit in a device. If many EdgeMatcher instances are created running in parallel, all using the FPGA acceleration, they may try to access the FPGA resource at the same time. The behavior is then that a match call will wait until the FPGA resource is available again. Image world coordinate system handling: The image (x,y)-pixelsize and origin are considered within the EdgeMatcher, all calculations are made in the image world coordinate system. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: The EdgeMatcher does not accept missing data images, turn off the missing data flag to use it anyway or use the EdgeMatcher3D. Object model: An object representation of the contours in the teach reference image is generated in a teach call. The center of the model, and also the rotation center, is the center of the teach region. Saving and loading a configuration: A trained EdgeMatcher instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.
Keywords
contour, find, matching, object, pattern, shape, locator
See also
Overview
create(), getDownsampleFactorLimits(), getEdgePoints(), getModelContours(), getModelPoints(), getTeachPose(), match(), setBackgroundClutter(), setDownsampleFactor(), setEdgeThreshold(), setMaxMatches(), setMinSeparation(), setProcessingUnit(), setRotationRange(), setScaleRange(), setTimeout(), teach(), toString()
Functions
create()
Creates a new edge matcher for object localization in 2D intensity images.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The new EdgeMatcher instance. |
locator = Image.Matching.EdgeMatcher.create()
getDownsampleFactorLimits()
A support function which outputs the minimum and maximum values of the downsample factor. In particular when FPGA acceleration is utilized there are memory limitations setting a minimal value for the downsample factor. The maximum downsample factor is derived from the minimum allowed downsampled image size to look for matches in.
Image.Matching.EdgeMatcher.setProcessingUnit, Image.Matching.EdgeMatcher.setDownsampleFactor
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
image |
CONST_OBJECT Image |
An image with the size that the EdgeMatcher will work on |
| Name | Type | Description |
|---|---|---|
minDsf |
FLOAT |
Minimum allowed downsample factor. |
maxDsf |
FLOAT |
Maximum allowed downsample factor. |
minDsf, maxDsf = Image.Matching.EdgeMatcher.getDownsampleFactorLimits(matcher, image)
getEdgePoints()
Deprecated: This function has been renamed to getModelPoints to align with the PointMatcher API. The functions give the same output. Get sample edges of the object represented as a vector of 2D Points. This function is intended for graphical feedback using representative points on edges of the reference object. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. Can only be called after a successful teach.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The matcher instance to use. |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
Edge points in internal model coordinates. |
points = Image.Matching.EdgeMatcher.getEdgePoints(matcher)
getModelContours()
Get object model contours for visualization purposes. Results are returned as polyline shape objects.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The matcher instance to use. |
| Name | Type | Description |
|---|---|---|
polylines |
OBJECT Shape |
Edge lines in internal model coordinates. |
polylines = Image.Matching.EdgeMatcher.getModelContours(matcher)
getModelPoints()
Get the object model as a vector of 2D Points of located edges. This function is intended for graphical feedback using representative points on edges of the reference object. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. Can only be called after a successful teach. Note: As it may be inefficient to overlay a lot of points in images, it is recommended to use the getModelContours function instead for graphical feedback.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The matcher instance to use. |
maxCount |
INT |
Optional parameter to specify the maximum number of control points along the polylines to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here. |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
Edge points in internal model coordinates. |
points = Image.Matching.EdgeMatcher.getModelPoints(matcher, 1000)
getTeachPose()
Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
teachPose |
OBJECT Transform |
2D pose transform transforming the object model to its position in the teach image, or nil if unsuccessful. |
teachPose = Image.Matching.EdgeMatcher.getTeachPose(matcher)
match()
Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to the match in the live image. For the EdgeMatcher, the output posed transforms are of 2D Transform type. They can be used with the Fixture object to transform other 2D objects and regions. The match scores are based on how well edge information in the image matches the object model. The status code indicates what happened during the call and may be set to any of the following values: * 0: Matching was successful (although no objects may have been found, there was no error). * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 210: Timeout, matching was aborted. Check the set time limit. * 220: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 230: Region error, something was wrong with the search region. * 240: Unteached matcher, the matcher is not successfully teached. * 260: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The matcher instance to use |
liveImage |
CONST_OBJECT Image |
The live image to find the object in. |
searchRegion |
CONST_AUTO |
Optional search region in the live image, either a pixel region or a closed 2D shape such as a rectangle. Edges are only detected within this region and it should cover the entire object to be found. |
| Name | Type | Description |
|---|---|---|
poseTransforms |
OBJECT Transform |
Pose transforms defining the location of each detected object. |
matchScores |
FLOAT |
A score between 0.0 and 1.0 for each detected object (high score means good match). |
status |
INT |
A status code indicating what happened during the call. |
transforms, scores, status = Image.Matching.EdgeMatcher.match(matcher, liveImage, searchRegion, priorRotation, priorScale)
setBackgroundClutter()
A setting that indicates to what level the live images supplied to the match function are expected to contain non-object edges. Keep this parameter at HIGH (default) if the image contains a lot of other edges, structures, noise, clutter in areas not belonging to the object of interest. Examples of such structures are barcodes and text which generate a lot of edge responses. For clean scenes this parameter can be set to MEDIUM or LOW to gain speed. Note however that it may be possible to work with higher downsample factors if this parameter is set to HIGH. Setting this parameter will invalidate any previous teach call.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
backgroundClutterLevel |
AUTO |
Set to the expected background clutter level, LOW, MEDIUM or HIGH. Default is HIGH. In a previous version of this function this input was a bool where 'true' maps to the MEDIUM enum and 'false' to the LOW enum. |
Image.Matching.EdgeMatcher.setBackgroundClutter(matcher, backgroundClutterLevel)
setDownsampleFactor()
Sets downsampling factor in the x- and y-dimensions of the image. If the original image has size (M,N), the downsampled image has size (M/d, N/d) where d is the downsampling factor. More downsampling will increase the speed but eventually will reduce the matching robustness. Especially, for small object or thin contours the downsampling cannot be set too low as the details will become washed out in the downsampled image. However, some downsampling can also be beneficial for the matching as noise and irrelevant edges are removed. Therefore, a good downsampling is usually somewhere between 2.0 and 10.0. Setting a high downsampling does not have an impact on the final matching position accuracy as matches are fine-tuned on finer image resolutions. For FPGA acceleration there is lower limit on the downsampling factor due to memory limitations. This limit is different for various devices but is usually around 5.0 to 6.0. Use the getDownsampleFactorLimits to find out the lower and upper limits on the downsample factor.
Image.Matching.EdgeMatcher.setBackgroundClutter, Image.Matching.EdgeMatcher.getDownsampleFactorLimits
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
downsampleFactor |
FLOAT |
A factor larger than or equal to 1.0. The default value is 8.0. |
Image.Matching.EdgeMatcher.setDownsampleFactor(matcher, 6.0)
setEdgeThreshold()
Sets the edge threshold, i.e., minimal edge strength. The edge strength is calculated as using a local image gradient filter so that smooth edges may generate weak edge responses. The default value is 50. For lower contrast edges one must reduce this value and for very sharp and high-contrast edges it should be raised. Check with the getModelContours() function the edges that are obtained. Setting this parameter will invalidate any previous teach call.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
threshold |
FLOAT |
Edge threshold. The default value is 50. |
Image.Matching.EdgeMatcher.setEdgeThreshold(matcher, 20)
setMaxMatches()
Sets the maximum number of objects to find in a match call. Note that the actual number found can be smaller than this number. Increasing the number of matches to consider is also a way to control the number of match candidates considered within the algorithm. Thus, in cluttered scenes it may be possible to increase robustness to increase this parameter even if one knows that there is only one object present at the end. This parameter can be updated in a teached matcher without re-teaching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
matchCount |
INT |
An integer larger than or equal to 1 specifying the maximum number of objects to find. The default value is 1. |
Image.Matching.EdgeMatcher.setMaxMatches(matcher, 3)
setMinSeparation()
Sets the minimum separation between the centers of object matches. The unit is in image world units (typically millimeters) taking the image pixel size into account. For 2D images the pixel size is by default 1.0, in which case the value equals the separation in pixels. This parameter only has effect if the number of matches to find is larger than 1. This parameter can be updated in a teached matcher without re-teaching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
minSeparation |
FLOAT |
The minimum separation between the centers of two objects in image world units. The default value is 50. |
Image.Matching.EdgeMatcher.setMinSeparation(matcher, 100)
setProcessingUnit()
Sets processing unit for the calculations. Some devices support FPGA acceleration of the EdgeMatcher. If this is the case the FPGA acceleration is set as default when the EdgeMatcher object is created.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
processingUnit |
Which type of processing unit to use. If there is FPGA support in the device it will be used as default, otherwise CPU. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if processing unit choice was successfully set. False if the processing unit or configuration is not supported. |
Image.Matching.EdgeMatcher.setProcessingUnit(matcher, "FPGA")
setRotationRange()
Sets rotation interval to search in relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. If prior orientation information is known, the prior rotation can be set to allow a more narrow search range. The final search range is then up to plus/minus the search range parameter starting from the prior rotation. These parameters can be updated in a teached matcher without re-teaching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
rotationRad |
FLOAT |
Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI (180 degrees), i.e., full rotation. |
priorRotationRad |
FLOAT |
Optional prior orientation in radians. If specified, the orientation search range is centered around this orientation. Default is zero (i.e. same orientation as teach object). |
Image.Matching.EdgeMatcher.setRotationRange(matcher, rotationRad, priorRotationRad)
setScaleRange()
Sets scale interval to search relative to the teach size. The end points are represented as scale factors. setScaleRange(0.8, 1.2) searches for objects appearing down to 20% smaller or larger than the teach object. Default is not to search in scale, i.e, scale range parameters [1.0, 1.0]. An optional prior scale can be set, this affects both the minimum and maximum scale (both limits are multiplied with the prior scale). The prior scale moves the entire scale search range and does not affect matching time. The prior scale accepts a larger range of values than the min and max scale parameters. If the object to find has a fixed non-unit scale relative to the teach object, or if prior information on the scale of the object is available, use the prior scale. The default value is 1.0. By setting both minScale and maxScale to 1.0, scale search is disabled but the prior scale parameter still has effect. These parameters can be updated in a teached matcher without re-teaching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
minScale |
FLOAT |
The smallest scale factor to search for. Lower limit is 0.8. Default value is 1.0. |
maxScale |
FLOAT |
The largest scale factor to search for. Upper limit is 1.2. Default value is 1.0. |
priorScale |
FLOAT |
Optional prior scale factor. Set to the expected scale of the object to find, relative to the size of the teach object. E.g. 1.25 if the object to find is 25% larger than the teach object. Min: 0.1. Max: 10 |
Image.Matching.EdgeMatcher.setScaleRange(matcher, minScale, maxScale, priorScale)
setTimeout()
Abort the match call if the match time exceeds a user-defined number of seconds. The main purpose is to protect against excessively long execution times, the granularity does not allow exact abortion at the given timeout parameter.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
timeoutSeconds |
FLOAT |
Time in seconds after which the algorithm should abort. The default value is 5 seconds. |
Image.Matching.EdgeMatcher.setTimeout(matcher, 2.0)
teach()
Teaches an object model from edges in an image. It is important to set the edge strength threshold properly for this to work. Graphical feedback from the teach process is obtained through the getModelContours function. The status code indicates what happened during the call and may be set to any of the following values: * 0: Teaching was successful. * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 110: Timeout, teaching was aborted. Check the set time limit. * 120: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 130: Region error, something was wrong with the teach region. * 160: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy. * 170: Model edge error, too few model edges were found. Check the edge threshold, the input image and that the teach region covers the object of interest.
Image.Matching.EdgeMatcher.getModelContours, Image.Matching.EdgeMatcher.getTeachPose, Image.Matching.EdgeMatcher.match
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use |
teachImage |
CONST_OBJECT Image |
The teach image. |
teachRegion |
CONST_AUTO |
A pixel region or a closed 2D shape defining which area to consider as containing object edges. |
| Name | Type | Description |
|---|---|---|
teachPoseTransform |
OBJECT Transform |
Pose transform of the object model, or nil if unsuccessful. |
status |
INT |
A status code indicating what happened during the call. |
teachPoseTransform, status = Image.Matching.EdgeMatcher.teach(matcher, teachImage, teachRegion)
toString()
Returns a human readable description of the matcher, including parameters.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
description |
STRING |
A description of the matcher object, or nil on failure. |
description = Image.Matching.EdgeMatcher.toString(matcher)
Image.Matching.EdgeMatcher3D
The EdgeMatcher3D is an extension of the EdgeMatcher for object matching in range images and heightmaps. See the EdgeMatcher documentation for information on the basic usage. The documentation below focuses on the extensions and differences to the EdgeMatcher. The most important additional parameters and difference for the EdgeMatcher3D are the following: - The EdgeMatcher3D additionally searches for height and tilt (rotation around the x- and y-axes) of objects. The function setFindTiltHeight() enables and disables these additional parameters in the search. Tilt and height estimation is turned on as default. Turn these off for increased speed and robustness if the objects of interest always have the same tilt or height. - As range images generally contain missing data pixels, there is a mandatory "reference height" parameter that is set using the setReferenceHeight(). The EdgeMatcher3D uses this parameter to replace missing data pixels internally. - The output of the EdgeMatcher3D are 3D pose transforms. These can be used together with the Fixture3D object for locate-inspect applications. - Teach and search regions have additional zMin and zMax parameters to specify limits along the z-dimension. Pixel types: The EdgeMatcher3D accepts uint16 pixel type images. Hardware acceleration: Some devices have FPGA-support for the EdgeMatcher3D. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. If there is FPGA support it is set as default, but note that the FPGA is not able to support all configurations, mainly there is a lower restriction on the downsample factor for memory limitation reasons. There is typically only one instance of the FPGA calculation unit in a device. If many EdgeMatcher3D instances are created running in parallel, all using the FPGA acceleration, they may try to access the FPGA resource at the same time. The behavior is then that a match call will wait until the FPGA resource is available again. Image world coordinate system handling: All parameters (thresholds, zMin, zMax, reference height) use the z-origin and z-pixelsize. That is, the parameters are interpreted in world units, typically in millimeters. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: Both images with and without missing data flag are accepted. If the input image has missing data, the reference height parameter must be set to handle missing data internally. Object model: An object representation of the contours in the teach reference image is generated in a teach call. The center of the model, and also the rotation center, is the center of the teach region. The center in the z-dimension is (zMin + zMax)/2. Saving and loading a configuration: The configuration of a trained EdgeMatcher handle instance can be saved and loaded (serialized/deserialized) using the Object.save() and Object.load() functions.
See also
Overview
create(), getDownsampleFactorLimits(), getModelContours(), getModelPlanePoints(), getModelPoints(), getTeachPose(), match(), proposeReferenceHeight(), setBackgroundClutter(), setDownsampleFactor(), setEdgeThreshold(), setFindTiltHeight(), setMaxMatches(), setMinSeparation(), setProcessingUnit(), setReferenceHeight(), setRotationRange(), setTimeout(), teach(), toString()
Functions
create()
Creates a new edge matcher for 3D object localization in range images.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The new instance. |
locator = Image.Matching.EdgeMatcher3D.create()
getDownsampleFactorLimits()
A support function which outputs the minimum and maximum values of the downsample factor. In particular when FPGA acceleration is utilized there are memory limitations setting a minimal value for the downsample factor. The maximum downsample factor is derived from the minimum allowed downsampled image size to look for matches in.
Image.Matching.EdgeMatcher3D.setProcessingUnit, Image.Matching.EdgeMatcher3D.setDownsampleFactor
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
image |
CONST_OBJECT Image |
An image with the size that the EdgeMatcher3D will work on. |
| Name | Type | Description |
|---|---|---|
minDsf |
FLOAT |
Minimum allowed downsample factor. |
maxDsf |
FLOAT |
Maximum allowed downsample factor. |
minDsf, maxDsf = Image.Matching.EdgeMatcher3D.getDownsampleFactorLimits(matcher, image)
getModelContours()
Gets object model contours for visualization purposes. Results are returned as polyline Shape3D objects.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The matcher instance to use. |
| Name | Type | Description |
|---|---|---|
polylines |
OBJECT Shape3D |
Edge lines in internal model coordinates. |
polylines = Image.Matching.EdgeMatcher3D.getModelContours(matcher)
getModelPlanePoints()
Gets object model points for visualization purposes. This function returns center points of planar patches.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The matcher instance to use. |
maxCount |
INT |
Optional parameter to specify the maximum number points to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here. |
| Name | Type | Description |
|---|---|---|
planarPoints |
OBJECT Point |
Vector of 3D planar points in internal model coordinates. |
planarPoints = Image.Matching.EdgeMatcher3D.getModelPlanePoints(matcher)
getModelPoints()
Gets object model points for visualization purposes. This function returns points along the edges of object. See also getModelContours.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The matcher instance to use. |
maxCount |
INT |
Optional parameter to specify the maximum number points to return. Default is 500 and absolute max is 5000. Note that one can obtain fewer points than the value specified here. |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
Edge points in internal model coordinates. |
points = Image.Matching.EdgeMatcher3D.getModelPoints(matcher)
getTeachPose()
Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
teachPose |
OBJECT Transform |
Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful. |
teachPose = Image.Matching.EdgeMatcher3D.getTeachPose(matcher)
match()
Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to the match in the live image. For the EdgeMatcher3D, the output pose transforms are of 3D Transform type. They can be used with the Fixture3D object to transform other 3D objects and regions. The match scores are based on how well edge information in the image matches the object model. Currently, only (x,y) locations of edges are included in the score calculation, meaning that a mismatch in z-dimension can still give a high score. Image world coordinate system handling: The two parameters zMin and zMax specify the range interval of the teach region. The parameters are interpreted in image world units, typically millimeters, taking the z-origin and z-pixelsize of the input image into account. The status code indicates what happened during the call and may be set to any of the following values: * 0: Matching was successful (although no objects may have been found, there was no error). * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 210: Timeout, matching was aborted. Check the set time limit. * 220: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 230: Region error, something was wrong with the search region. * 240: Unteached matcher, the matcher is not successfully teached. * 250: Reference plane error, something was wrong with the reference height for missing data. * 260: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The matcher instance to use |
liveImage |
CONST_OBJECT Image |
The live image to find the object in. |
searchRegion |
CONST_AUTO |
Optional search region in the live image, either a pixel region or a closed 2D shape such as a rectangle. Edges are only detected within this region and it should cover the entire object to be found. |
zMin |
FLOAT |
Optional minimum value for z heights in world units (millimeters). Only edges above this level are included as features for the matching. If not set, a large negative number is used as default. |
zMax |
FLOAT |
Optional maximum value for z heights in world units (millimeters). Only edges below this level are included as features for the matching. If not set, a large positive number is used as default. |
| Name | Type | Description |
|---|---|---|
poseTransforms |
OBJECT Transform |
Pose transforms defining the location of each detected object. |
matchScores |
FLOAT |
A score between 0.0 and 1.0 for each detected object (high score means good match). |
status |
INT |
A status code indicating what happened during the call. |
transforms, scores = Image.Matching.EdgeMatcher3D.match(matcher, liveImage)
proposeReferenceHeight()
Tries to estimate a reference height using valid pixels outside the teach region. Use this function carefully as it can give inaccurate results, for example if the teach region covers only the object partially.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use |
teachImage |
CONST_OBJECT Image |
The teach image. |
teachRegion |
CONST_AUTO |
A pixel region or a closed 2D shape defining which area to consider as containing object edges. |
| Name | Type | Description |
|---|---|---|
referenceHeight |
FLOAT |
An estimated reference height in image world units, typically millimeters.. Returns nil if height estimation fails. |
referenceHeight = Image.Matching.EdgeMatcher3D.proposeReferenceHeight(matcher, teachImage, teachRegion)
setBackgroundClutter()
A setting that indicates to what level the live images supplied to the match function are expected to contain non-object edges, e.g., noise and other clutter structures. The default setting is "MEDIUM". For very cluttered scenes it is possible to use a "HIGH" setting. Setting this parameter will invalidate any previous teach call.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
backgroundClutterLevel |
AUTO |
Set to the expected background clutter level, LOW, MEDIUM or HIGH. Default is MEDIUM. |
Image.Matching.EdgeMatcher3D.setBackgroundClutter(matcher, backgroundClutterLevel)
setDownsampleFactor()
Sets downsample factor in the x- and y-dimensions of the image. If the original image has size (M,N), the downsampled image has size (M/d, N/d) where d is the downsample factor. More downsampling will increase the speed but eventually will reduce the matching robustness. Especially, for small object or thin contours the downsampling cannot be set too low as the details will become washed out in the downsampled image. However, some downsampling can also be beneficial for the matching as noise and irrelevant edges are removed. Therefore, a good downsampling is usually somewhere between 2.0 and 10.0. Setting a high downsampling does not have an impact on the final matching position accuracy as matches are fine-tuned on finer image resolutions.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
downsampleFactor |
FLOAT |
A factor larger than or equal to 1.0. The default value is 8.0. |
Image.Matching.EdgeMatcher3D.setDownsampleFactor(matcher, downsampleFactor)
setEdgeThreshold()
Sets the edge threshold, i.e., minimal edge strength. The edge strength is calculated as using a local image gradient filter so that smooth edges may generate weak edge responses. The default value is 10. Check with the getModelPoints() or the getModelContours() function the edges that are obtained. Setting this parameter will invalidate any previous teach call. Image world coordinate system handling: The edge threshold is interpreted in the image world coordinate system, i.e., typically in millimeters. The threshold is converted internally to a raw pixel value threshold using the z-origin and z-pixelsize of the image.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
threshold |
FLOAT |
Edge threshold interpreted in the image world coordinate system. The default value is 10 for EdgeMatcher3D. |
Image.Matching.EdgeMatcher3D.setEdgeThreshold(matcher, threshold)
setFindTiltHeight()
Flags to find the tilt and/or height of objects relative to the teach pose. Depending on the application, one may for example know that the tilt and or height is always the same as for the teach object. If so, turn off the estimation of these parameters for increased speed and robustness. If tilt-search is on, height-search is turned on automatically. Setting this parameter will invalidate any previous teach call. The maximum tilt angle the algorithm can find is about 10 - 15 degrees relative to the teach pose, for higher tilts the algorithm may not match robustly.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The matcher instance to use. |
findTilt |
BOOL |
Set to true to find tilt of matched objects. Default is true. |
findHeight |
BOOL |
Set to true to find height of matched objects. Default is true. |
Image.Matching.setFindTiltHeight(matcher, findTilt, findHeight)
setMaxMatches()
Sets the maximum number of objects to find in a match call. Note that the actual number found can be smaller than this number. This parameter can be updated in a teached matcher without re-teaching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
matchCount |
INT |
An integer larger than or equal to 1 specifying the maximum number of objects to find. The default value is 1. |
Image.Matching.EdgeMatcher3D.setMaxMatches(matcher, matchCount)
setMinSeparation()
Sets the minimum separation in the (x,y)-dimension between the centers of object matches. This parameter only has effect if the number of matches to find is larger than 1. This parameter can be updated in a teached matcher without re-teaching. Image world coordinate system handling: The unit is in image world units (typically millimeters) taking the image (x,y)-pixelsizes into account.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
minSeparation |
FLOAT |
The minimum separation between the centers of two objects in image world units. The default value is 50. |
Image.Matching.EdgeMatcher3D.setMinSeparation(matcher, minSeparation)
setProcessingUnit()
Sets processing unit for the calculations. Some devices support FPGA acceleration of the EdgeMatcher3D. If this is the case the FPGA acceleration is set as default when the EdgeMatcher3D object is created.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
processingUnit |
Which type of processing unit to use. If there is FPGA support in the device it will be used as default, otherwise CPU. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if processing unit choice was successfully set. False if the chosen processing unit is not supported. |
Image.Matching.EdgeMatcher3D.setProcessingUnit(matcher, "FPGA")
setReferenceHeight()
Sets a reference height for missing data handling. This value is used to replace missing data pixels within the algorithm. Use the height of the floor, belt or any other application-dependent height. Setting this parameter is mandatory if the input images have the missing data flag on. If missing data has been removed before calling the EdgeMatcher3D, this parameter has no effect. This parameter can be updated in a teached matcher without re-teaching. A suggested reference height can be obtained using the proposeReferenceHeight()-function. Image world coordinate system handling: The reference height is interpreted in the image world coordinate system, typically in millimeters, considering the z-origin and z-pixelsize of the image.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The matcher instance to use. |
referenceHeight |
FLOAT |
Reference height specified in world units, e.g., millimeters. |
Image.Matching.EdgeMatcher3D.setReferenceHeight(matcher, referenceHeight)
setRotationRange()
Sets rotation interval around the z-axis to search in relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. This parameter can be updated in a teached matcher without re-teaching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
rotationRad |
FLOAT |
Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI. |
Image.Matching.EdgeMatcher3D.setRotationRange(matcher, rotationRad)
setTimeout()
Abort the match call if the match time exceeds a user-defined number of seconds. The main purpose is to protect against excessively long execution times, the granularity does not allow exact abortion at the given timeout parameter.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
timeoutSeconds |
FLOAT |
Time in seconds after which the algorithm should abort. The default value is 5 seconds. |
Image.Matching.EdgeMatcher3D.setTimeout(matcher, timeoutSeconds)
teach()
Teaches an object model from edges in an image. It is important to set the edge strength threshold properly for this to work. Graphical feedback from the teach process is obtained through the getModelPoints() or getModelContours() functions. The teach procedure extracts both edge information and planar patches within the teach region. The latter are used to estimate tilt and height parameters in match. Image world coordinate system handling: The two parameters zMin and zMax specify the range interval of the teach region. The parameters are interpreted in image world units, typically millimeters, taking the z-origin and z-pixelsize of the input image into account. The status code indicates what happened during the call and may be set to any of the following values: * 0: Teaching was successful. * 10: Logical error, e.g. missing parameters or parameters outside the permissible range, see the printed error message. * 90: Error not related to any of the other categories, see the printed error message. * 110: Timeout, teaching was aborted. Check the set time limit. * 120: Image error, something was wrong with the input image, e.g. invalid, too small, unsupported type. * 130: Region error, something was wrong with the teach region. * 150: Reference plane error, something was wrong with the reference height for missing data. * 160: FPGA error, something was wrong with the FPGA, e.g. too large image or the FPGA was busy. * 170: Model edge error, too few model edges were found. Check the edge threshold, the input image and that the teach region covers the object of interest. * 180: Model plane error, too few planar probes were found. See status code 170.
Image.Fixture3D, Image.Matching.EdgeMatcher3D.getModelContours, Image.Matching.EdgeMatcher3D.match
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use |
teachImage |
CONST_OBJECT Image |
The teach image. |
teachRegion |
CONST_AUTO |
A pixel region or a closed 2D shape defining which area to consider as containing object edges. |
zMin |
FLOAT |
Optional minimum value for z heights in world units (millimeters). Only edges and planar points above this level are included in the model. If not set, a large negative number is used as default. |
zMax |
FLOAT |
Optional maximum value for z heights in world units (millimeters). Only edges and planar points below this level are included in the model. If not set, a large positive number is used as default. |
| Name | Type | Description |
|---|---|---|
teachPoseTransform |
OBJECT Transform |
Pose transform of the object model, or nil if unsuccessful. |
status |
INT |
A status code indicating what happened during the call. |
teachPoseTransform, status = Image.Matching.EdgeMatcher3D.teach(matcher, teachImage, teachRegion)
toString()
Returns a human readable description of the matcher, including parameters.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
description |
STRING |
A description of the matcher object. |
description = Image.Matching.EdgeMatcher3D.toString(matcher)
Image.Matching.PatternMatcher
Finds an object in an image based on its pixel pattern. Teach the object from a reference image and call match to find the location of the same object in a live image. The PatternMatcher primarily searches for translated and rotated objects. Search in scale can be activated. Results are given in pose transforms which describe how the object model is transformed to matched positions in the live image. Each match gets a score between 0.0 and 1.0 where 1.0 means a perfect match. The PatternMatcher is often used together with the Fixture object that facilitates local coordinate transforms based on the result of the PatternMatcher. The most important parameters for the PatternMatcher are the following: - Downsample factor: The PatternMatcher works internally on downsampled images for computational performance reasons. The downsample factor is the most important parameter for the speed versus robustness trade-off. A initial choice of downsample factor could be one that generates a downsampled image of size about 150 x 150. That is, if images of size 1024 x 1024 are used, one could start experimenting with a downsample factor of around 7. A warning will be issued during teach if the downsample factor makes the object model too small. - Rotation range: The rotation range parameter should be selected to be as narrow as possible both for computational reasons and for robustness reasons. If it is known that the target object only can appear within a certain rotation interval, make sure to reduce the rotation range search parameter.
Keywords
correlation, matching, pixel, template, locator
Overview
create(), getDownsampleFactor(), getMaxMatches(), getMinSeparation(), getModelBoundingBox(), getRotationRange(), getTeachPose(), getTimeout(), match(), setDownsampleFactor(), setEdgeSensitivity(), setMaxMatches(), setMinSeparation(), setRotationRange(), setScaleSearch(), setTimeout(), teach(), toString()
Functions
create()
Creates a new pattern matcher for 2D object localization.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The new instance. |
locator = Image.Matching.PatternMatcher.create()
getDownsampleFactor()
Gets the current downsample parameter setting.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
downsampleFactor |
FLOAT |
The current downsample factor. |
downsampleFactor = Image.Matching.PatternMatcher.getDownsampleFactor(locator)
getMaxMatches()
Gets the current maximum number of objects to find.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
matchCount |
INT |
The current maximum number of objects to find. |
matchCount = Image.Matching.PatternMatcher.getMaxMatches(locator)
getMinSeparation()
Gets the current minimum separation between centers of object matches.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
minSeparation |
FLOAT |
The minimum separation between the centers of two objects in image world units. |
minSeparation = Image.Matching.PatternMatcher.getMinSeparation(locator)
getModelBoundingBox()
Get a bounding box of the teach object centered on the image world origin. It can be transformed directly by the pose transformations obtained from match to visualize matching results.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
modelBox |
OBJECT Shape |
A rectangle Shape representing the bounding box of the teach region, or nil if unsuccessful. |
modelBox = Image.Matching.PatternMatcher.getModelBoundingBox(locator)
getRotationRange()
Gets the current rotation range parameter.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
rotationRad |
FLOAT |
The current rotation range. |
rotationRad = Image.Matching.PatternMatcher.getRotationRange(locator)
getTeachPose()
Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
teachPose |
OBJECT Transform |
Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful. |
teachPose = Image.Matching.PatternMatcher.getTeachPose(matcher)
getTimeout()
Gets the selected timeout for matching.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
timeoutSeconds |
FLOAT |
Time in seconds after which the algorithm will abort. |
timeoutSeconds = Image.Matching.PatternMatcher.getTimeout(locator)
match()
Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms, one transform for each found match. The transform describes how the object model is transformed to matched positions in the live image.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The matcher instance to use. |
liveImage |
CONST_OBJECT Image |
The live image to find the object in. |
searchRegion |
CONST_OBJECT Shape |
Optional search region in the live image, must be a rectangle. |
| Name | Type | Description |
|---|---|---|
poseTransforms |
OBJECT Transform |
Pose transforms defining the location of each detected object. |
matchScores |
FLOAT |
A score between 0.0 and 1.0 for each detected object (high score means good match). |
transforms, scores = Image.Matching.PatternMatcher.match(locator, liveImage)
setDownsampleFactor()
Sets the downsample factor. Increasing this value will reduce computation time, but also reduce accuracy.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
downsampleFactor |
FLOAT |
A factor larger than or equal to 1.0. The default value is 16. |
Image.Matching.PatternMatcher.setDownsampleFactor(locator, 10.0)
setEdgeSensitivity()
Sets sensitivity to edge pixel intensity values used when matching. Sharp edges generate large errors for noisy edge positions, setting a low sensitivity (default) reduces errors due to small edge position variations among objects and typically increases the performance of the matcher.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
edgeSensitivity |
ENUM EdgeSensitivity |
Sensitivity to edge pixels (e.g.: LOW, HIGH). |
Image.Matching.PatternMatcher.setEdgeSensitivity(locator, edgeSensitivity)
setMaxMatches()
Sets the maximum number of objects to find in a match call. The actual number of matches found can be smaller than this number. This parameter can be changed without re-teaching.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
matchCount |
INT |
An integer larger or equal than 1 specifying the maximum number of object to find. |
Image.Matching.PatternMatcher.setMaxMatches(locator, 3)
setMinSeparation()
Sets the minimum separation between the centers of object matches. The unit is in image world units (typically millimeters) taking the image pixel size into account. For 2D images the pixel size is by default 1.0, in which case the value equals the separation in pixels. This parameter can be changed without re-teaching.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
minSeparation |
FLOAT |
The minimum separation between the centers of two objects in image world units. The default value is 50. |
Image.Matching.PatternMatcher.setMinSeparation(locator, 50)
setRotationRange()
Sets the rotation interval to search in, relative to the teach orientation. Narrowing the rotation search range speeds up the matching considerably. The search range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
rotationRad |
FLOAT |
Angle in radian units, the maximum deviation from the original object orientation to search for. The default value is PI/16. |
Image.Matching.PatternMatcher.setRotationRange(locator, 3.1415/16)
setScaleSearch()
Activates searching for objects of different scales, from minimalSize to maximalSize. By default, no scale search is active, corresponding to setScaleSearch(1.0, 1.0).
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use |
minimalScale |
FLOAT |
Size of objects relative to teach object, 0.5 searches for objects down to half the size of the teach object. |
maximalScale |
FLOAT |
Size of objects relative to teach object, 2.0 searches for objects up to double the size of the teach object. |
Image.Matching.PatternMatcher.setScaleSearch(locator, minimalScale, maximalScale)
setTimeout()
Abort the match call if the match time exceeds a user-defined number of seconds. The default value is 5 seconds. This parameter can be changed without re-teaching.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
timeoutSeconds |
FLOAT |
Time in seconds after which the algorithm should abort. |
Image.Matching.PatternMatcher.setTimeout(locator, 10.0)
teach()
Teaches an object model from an image. It is important to set a reasonable downsample factor and the desired rotational range beforehand.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
teachImage |
CONST_OBJECT Image |
The teach image. |
teachRegion |
CONST_AUTO |
A pixel region or closed 2D shape defining which area to consider as containing the object. |
| Name | Type | Description |
|---|---|---|
teachPoseTransform |
OBJECT Transform |
Pose transform of the object model, or nil if unsuccessful. |
teachPose = Image.Matching.PatternMatcher.teach(locator, teachImage, teachRegion)
toString()
Returns a human readable description of the matcher, including parameters.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The matcher instance to use. |
| Name | Type | Description |
|---|---|---|
description |
STRING |
A description of the matcher object, or nil on failure. |
description = Image.Matching.PatternMatcher.toString(handle)
Image.Matching.PatternVerifier
Verifies a pixel value pattern. Create a new instance using the create function, set parameters using the set functions, teach the correct pattern from a reference image and call verify to find the similarity to the taught pattern. The PatternVerifier can tolerate some errors in the given translation, rotation and scale of the pattern to verify, however for large uncertainties, use a matcher object to find the pattern first. By default all tolerances are set to zero. Results are given as similarity scores as well as an image indicating where the differences are. A refined pose is returned.
Keywords
checking, comparison, pixel, verification, correlation
See also
Overview
Functions
create()
Creates a new pattern verifier for pixel value pattern verification.
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The new instance. |
verifier = Image.Matching.PatternVerifier.create()
generateOverlay()
Generates an overlay PixelRegion by thresholding a difference image. The overlay is transformed to match the latest live image and refined pose.
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The instance to use. |
differenceImage |
CONST_OBJECT Image |
Difference image to threshold. |
threshold |
FLOAT |
Threshold for difference image, all pixels with values above the threshold will be included in the pixel region. |
| Name | Type | Description |
|---|---|---|
overlay |
OBJECT Image.PixelRegion |
Overlay pixel region, or nil if unsuccessful. |
overlay = Image.Matching.PatternVerifier.generateOverlay(verifier, differenceImage, threshold)
getModelBoundingBox()
Get a bounding box of the teach object centered on the image world origin. It can be transformed directly by the pose transformations sent to and obtained from verify to visualize the working area of the verifier.
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
modelBox |
OBJECT Shape |
A rectangle Shape representing the bounding box of the teach region, or nil if unsuccessful. |
modelBox = Image.Matching.PatternVerifier.getModelBoundingBox(verifier)
setEdgeSensitivity()
Sets the sensitivity to edge pixel intensity values used when verifying. Sharp edges generate large errors for noisy edge positions, setting a low sensitivity (default) reduces errors due to small edge position variations among objects.
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The instance to use. |
edgeSensitivity |
ENUM EdgeSensitivity |
Sensitivity to edge pixels (e.g.: HIGH, LOW). |
Image.Matching.PatternVerifier.setEdgeSensitivity(verifier, edgeSensitivity)
setPositionTolerance()
Sets how much the position of the pattern may deviate from the pose given to the verify function. Narrowing the translational search range speeds up the verification considerably. The range is given as a distance in world units, allowing the pattern to be translated up to plus/minus the distance along both dimensions.
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The instance to use. |
translation |
FLOAT |
Allowed distance in world units. The default tolerance is zero. |
Image.Matching.PatternVerifier.setPositionTolerance(verifier, 2.0)
setRotationTolerance()
Sets how much the rotation of the pattern may deviate from the pose given to the verify function. Narrowing the rotation search range speeds up the verification considerably. The range is given as an angle in radian units. The rotation range interval is plus/minus the specified angle.
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The instance to use. |
rotationRad |
FLOAT |
Angle in radian units, the maximum deviation from the given object orientation to search for. The default tolerance is zero. |
Image.Matching.PatternVerifier.setRotationTolerance(verifier, 3.1415/16)
setScaleTolerance()
Sets how much the scale of the pattern may deviate from the pose given to the verify function. Narrowing the scale search range speeds up the verification considerably. The range is given as the minimum and maximum size of the pattern, relative to the transformation supplied to the verify function. The default is no scale change tolerance, i.e., setScaleTolerance(1.0, 1.0).
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The instance to use. |
minimumScale |
FLOAT |
Minimum relative scale to accept, e.g. setting to 0.9 allows pattern sizes down to 90%. |
maximumScale |
FLOAT |
Maximum relative scale to accept, e.g. setting to 1.1 allows pattern sizes up to 110%. |
Image.Matching.PatternVerifier.setScaleTolerance(verifier, 0.9, 1.1)
setTimeout()
Abort the verify call if the verify time exceeds a user-defined number of seconds. The default value is 5 seconds.
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The instance to use. |
timeoutSeconds |
FLOAT |
Time in seconds after which the algorithm should abort. |
Image.Matching.PatternVerifier.setTimeout(verifier, 2.0)
teach()
Teaches a pattern from an image. The returned pose is usually appended to a Fixture related to the main inspected object.
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The instance to use. |
teachImage |
CONST_OBJECT Image |
The teach image. |
teachRegion |
CONST_OBJECT Image.PixelRegion |
A pixel region defining which area to consider as containing the pattern. |
| Name | Type | Description |
|---|---|---|
teachPoseTransform |
OBJECT Transform |
Pose transform of the pattern, or nil if unsuccessful. |
teachPose = Image.Matching.PatternVerifier.teach(verifier, teachImage, teachRegion)
toString()
Returns a human readable description of the pattern verifier, including parameters.
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
description |
STRING |
A description of the verifier, or nil on failure. |
description = Image.Matching.PatternVerifier.toString(verifier)
verify()
Verifies a pattern by comparing to the teach pattern. A teach call must be made first. Some errors in the pose can be tolerated by setting the respective tolerance values.
| Name | Type | Description |
|---|---|---|
verifier |
HANDLE |
The instance to use. |
liveImage |
CONST_OBJECT Image |
The live image to verify the pattern in. |
pose |
CONST_OBJECT Transform |
The pose of the pattern to be verified, usually obtained from a Fixture. |
| Name | Type | Description |
|---|---|---|
score |
FLOAT |
A score between 0.0 and 1.0, or nil if unsuccessful. High score means the pattern is similar to the teach pattern. |
differenceImage |
OBJECT Image |
The difference image, indicating where the patterns differ, or nil if unsuccessful. Pixel values close to zero indicate areas where the patterns match. The default image contains the absolute pixel value differences between the live image and the transformed teach pattern. The difference image is sampled in an object-centered coordinate system with the origin in the center of the image, and cropped to the bounding box of the teach pattern. Any indications in the difference image should be transformed using the refinedPose to obtain the corresponding position in the live image. |
refinedPose |
OBJECT Transform |
The refined pose of the pattern, or nil if unsuccessful. If all tolerances are set to zero, this will be equal to the given pose. |
score, differenceImage, refinedPose = Image.Matching.PatternVerifier.verify(verifier, liveImage, pose)
Image.Matching.PointMatcher
Finds an object in an image based on feature points. Salient points are found on the reference object and similar points are searched for in the live images. Teach the object from a reference image and call match to find the location of the same object in a live image. The strength of the PointMatcher relative the EdgeMatcher is for objects whose appearance can be described in terms of textured pattern rather than clear edges or contours. The PointMatcher can also easily find large scale or perspective changes which the EdgeMatcher cannot. The outputs from the PointMatcher are a so-called pose transform and a match score. The pose transform is a Transform object which transforms the model points extracted in the teach step to the matched location in the live image. The PointMatcher is often used together with the Fixture object that facilitates local coordinate transforms based on the pose transform. The match score is a number between 0.0 and 1.0 indicating the fraction of model points that have a match in the input image. The most important parameters for the PointMatcher are the following: - Pose type: This parameter tells the PointMatcher which type of appearance change to look for in the match process, e.g., does the object of interest change size relative to the teach object, does the camera position change leading to a perspective change of the imaged object, etc.? Restrict the pose type as much as possible for a more robust matching. By default, the pose type is restricted and must explicitly be set to allow more general pose transforms. See the documentation of the setPoseType-function for more information. - Pose variability: If the object of interest is imaged from very different angles or distances, leading to large perspective or scale changes, set the pose variability to HIGH for more robustness. Otherwise, set the pose variability to LOW for a higher matching speed. Use the setPoseVariability-function to set the pose variability. - Point count: The target number of salient points to extract. Fewer points will make the matching faster, but with too few points the matching will fail. Use setPointCount() to reduce the number of points. - Downsample factor: Tells the PointMatcher to work on a downsampled version of the input image. This can increase speed and in some cases even robustness if the original image is of high-resolution. Setting the downsample factor too high reduces the robustness though as the feature points in the ensuing low resolution image are not distinct enough. - Rotation range: The rotation range narrows the expected rotations relative to the teach pose. This parameter does not affect matching speed but increases robustness as false matches can be rejected. Set this range as narrow as possible but still wide enough to let valid matches through. - Scale range: The scale range narrows the expected scale change to the teach pose. This parameter does not affect matching speed but increases robustness as false matches can be rejected. Set this range as narrow as possible but still wide enough to let valid matches through. Restrictions: - Only uint8 images are accepted. - The PointMatcher can currently only find 1 object instance per image. Image world coordinate system handling: The image (x,y)-pixelsize and origin are considered, all calculations are made in the image world coordinate system. The output pose transforms are also expressed in the image world coordinate system. Missing data handling: The PointMatcher does not accept missing data images, remove missing data first before usage.
Keywords
descriptor, feature point, interest point, keypoint, landmark, matching, object, perspective, locator
Overview
Functions
create()
Creates a new point matcher for 2D object localization.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The new instance. |
locator = Image.Matching.PointMatcher.create()
getDetectedPoints()
Fetches two lists with salient points that were detected in the live image during the last match call. Points are returned in world coordinates and are intended to be plotted directly on the live image for graphical feedback. The first list contains all detected points while the second list only contains those points that were matched and found to be geometrically consistent with the corresponding model point under the found pose transformation.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
detectedPointsWorld |
OBJECT Point |
Detected salient points during the last call to match, may be empty. |
matchedPointsWorld |
OBJECT Point |
Matched points in the last live image, in world coordinates. The matched points are a subset of the detected salient points. |
detectedPointsWorld, matchedPointsWorld = Image.Matching.PointMatcher.getDetectedPoints(locator)
getModelPoints()
Gets the list of salient points detected during the last teach call as a vector of 2D Points. The points are returned in internal model coordinates and must be transformed using a pose transform to overlay them onto the teach or live image. A maximum number of points to return may be specified. The default is to return all points. This function is intended for graphical feedback. Note: to control the number of points detected in the image and used when matching, use the setPointCount function.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
maxCount |
INT |
Optional parameter to specify the maximum number of points to return. Default is to return all points. Note that one can obtain fewer points than the value specified here. |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
Salient model points in internal model coordinates, may be empty. |
points = Image.Matching.PointMatcher.getModelPoints(locator, maxCount)
getTeachPose()
Returns the teach pose that was created and returned by the last teach call. If the last teach was unsuccessful, nil is returned.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
teachPose |
OBJECT Transform |
Pose transform transforming the object model to its position in the teach image, or nil if unsuccessful. |
teachPose = Image.Matching.PointMatcher.getTeachPose(matcher)
match()
Finds objects in an image by matching with the teach model. A teach call must be made first. The output is a vector of pose transforms with one or zero entries, or nil. An empty vector indicates that no object was found while nil indicates that the matcher encountered an error. The transform describes how the object model is transformed to matched positions in the live image. The optional search region indicates where salient points will be extracted and should include the entire area where the object may appear. By default, the entire image is used. Use getDetectedPoints after match to visualize detected salient points in the live image and salient points matched to the model.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The matcher instance to use. |
liveImage |
CONST_OBJECT Image |
The live image to find the object in. |
searchRegion |
CONST_OBJECT Shape |
Optional search region in the live image, must be a rectangle. |
| Name | Type | Description |
|---|---|---|
poseTransforms |
OBJECT Transform |
Pose transform defining the location of any detected object. Note that this is a vector with at most one element/transform for future compatibility when adding multiple matches. |
matchScores |
FLOAT |
A score between 0.0 and 1.0 for any detected object (high score means good match). Note that this is a vector with at most one element/score for future compatibility when adding multiple matches. |
inlierRMS |
FLOAT |
The root mean squared error among inlier points in world coordinates (lower is better). Note that this is a vector with at most one element/value for future compatibility when adding multiple matches. |
poseTransforms, matchScores, inlierRMS = Image.Matching.PointMatcher.match(locator, liveImage)
setDownsampleFactor()
Sets the factor in the x- and y-dimensions for the internal downsampling of the image. Increasing this value will reduce the time required for detecting salient points. A larger downsampling factor may improve results in cases where the image structure is smooth or slightly out of focus. A higher downsampling factor reduces the accuracy of the estimated pose.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. Default is 2.0. |
downsampleFactor |
FLOAT |
A factor larger than or equal to 1.0. |
Image.Matching.PointMatcher.setDownsampleFactor(matcher, downsampleFactor)
setIterations()
Sets the maximum number of iterations in the geometrical robust fitting step. Decreasing this parameter makes the geometrical matching faster, however using too small values, good matches may be missed. When a match with high probability of being the correct one is found, fewer iterations may be used. The number of iterations set here is also used to control the probability threshold, where a higher number of iterations corresponds to requiring a higher probability of a correct match before stopping the iteration in advance.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
iterations |
INT |
Number of iterations, must be larger than one, the default is 5000. |
Image.Matching.PointMatcher.setIterations(locator, iterations)
setOutlierMargin()
Set the outlier margin in world units, must be greater than zero. The point matcher searches for the transform that is supported by the highest number of salient points. This setting determines how far a transformed model point can be from the corresponding live image point before it is considered an outlier and not supporting the current transform hypothesis. Decreasing this parameter will require the salient points of the template and live images to be geometrically more coherent. A too small value will remove almost all point match candidates, which will reduce object match accuracy significantly.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
margin |
FLOAT |
Outlier margin in world units, the default is 5.0. |
Image.Matching.PointMatcher.setOutlierMargin(locator, margin)
setPointCount()
Sets the desired number of salient points to detect in an image. The final number of points may be larger or smaller. The desired number of points is related to the full image. For a part of an image, the number of found points is lower in general.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
desiredPointCount |
INT |
A larger number generates more keypoints, default 1000. |
Image.Matching.PointMatcher.setPointCount(locator, desiredPointCount)
setPoseType()
The pose type puts a limit on the generality of pose transforms returned by the match function. In the following list, the first option is the most restrictive and every new type contains all previously listed types as special cases. "RIGID" - Searches for objects whose image appears translated and rotated. The scale range is ignored in this mode. Set rotation range to zero for pure translations. "SIMILARITY" - Searches for objects whose image appears translated, rotated and uniformly scaled. This is the default option. Set rotation range to zero for translation and scaling only. "AFFINE" - Searches for objects whose image appears translated, rotated, non-uniformly scaled and skewed. "HOMOGRAPHY" - This is the most general transform, it allows e.g. out-of-plane rotation for flat objects.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
poseTransformType |
The type of pose transformation to allow when searching for matching objects. |
Image.Matching.PointMatcher.setPoseType(locator, poseTransformType)
setPoseVariability()
Set to the expected variability in pose of the objects in the live image. Setting a higher variability will use more robust salient point detectors and descriptors but those will be slower in most cases. In general, try the lowest setting first and change to higher settings if required. "HIGH" - The default value, more robust but also slower in general. "LOW" - Faster in general and should be fine for any rotation, scale changes up to at least 30% and small perspective effects. When using this mode, the image size in pixels must be the same for all images.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
variability |
ENUM PoseVariability |
The expected pose variability of objects in the live image. |
Image.Matching.PointMatcher.setPoseVariability(locator, variability)
setRotationRange()
Sets rotation interval to search within, in relation to the teach orientation. The search range is given as a positive angle in radians. The rotation range interval is plus/minus the specified angle. The default value is PI radians, i.e., equal to a full rotation of plus/minus 180 degrees. For the point matcher, the search time is not affected by the rotation range. A too narrow range will remove all tentative matches. If prior orientation information is known, the prior rotation can be set to allow a more narrow search range. The final search range is then up to plus/minus the search range parameter starting from the prior rotation. These parameters can be updated in a teached matcher without re-teaching. When pose type is set to RIGID or SIMILARITY, setting the rotation range to zero will force the matcher to look for pure translations, or translation and scaling only.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
rotationRad |
FLOAT |
Angle in radians, the maximum deviation from the original object orientation to search for. The default value is PI. Input is silently clamped to the range from 0 to PI. |
priorRotationRad |
FLOAT |
Optional prior orientation in radians. If specified, the orientation search range is centered around this orientation. Default is zero (i.e. same orientation as teach object). |
Image.Matching.PointMatcher.setRotationRange(matcher, rotationRad)
setScaleRange()
Sets scale interval where objects are expected to appear. Tentative objects with a scale outside the scale range are discarded. Default range is from 0.5 to 2.0, searching for object from half to twice the size of the teach object. For transform types without a specific scale (affine and homogeneous), an approximate apparent scale is used. The scale range is ignored when the matcher is in rigid mode. For the point matcher, the search time is not affected by the scale range. A too narrow range will remove all tentative matches. An optional prior scale can be set, this affects both the minimum and maximum scale (both limits are multiplied with the prior scale). The prior scale accepts a larger range of values than the min and max scale parameters. If the object to find has a fixed non-unit scale relative to the teach object, or if prior information on the scale of the object is available, use the prior scale. The default value is 1.0. By setting both minScale and maxScale to 1.0, scale search is disabled but the prior scale parameter still has effect. These parameters can be updated in a teached matcher without re-teaching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
The instance to use. |
minScale |
FLOAT |
The smallest scale factor to allowed. |
maxScale |
FLOAT |
The largest scale factor to allowed. |
priorScale |
FLOAT |
Optional prior scale factor. Set to the expected scale of the object to find, relative to the size of the teach object. E.g. 1.25 if the object to find is 25% larger than the teach object. |
Image.Matching.PointMatcher.setScaleRange(matcher, minScale, maxScale)
setTimeout()
Abort the match call if the match time exceeds a user-defined number of seconds. The default value is 5 seconds.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
timeoutSeconds |
FLOAT |
Time in seconds after which the algorithm should abort. |
Image.Matching.PointMatcher.setTimeout(locator, timeoutSeconds)
teach()
Teaches an object model from an image. Use getModelPoints after teach to visualize the detected salient points on the teach object.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
teachImage |
CONST_OBJECT Image |
The teach image. |
teachRegion |
CONST_AUTO |
A pixel region or closed 2D shape defining which area to consider as containing the object. |
| Name | Type | Description |
|---|---|---|
teachPoseTransform |
OBJECT Transform |
Pose transform of the object model, or nil if unsuccessful. |
teachPose = Image.Matching.PointMatcher.teach(locator, teachImage, teachRegion)
toString()
Get a user-friendly string description of the matcher. The parameters are the internal parameters of the matcher, call teach for parameter changes to take effect and appear in the description string.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
description |
STRING |
User-friendly description of the matcher. |
description = Image.Matching.PointMatcher.toString(locator)
Image.OCR
Image.OCR.Halcon
Overview
Functions
findTextLineOrientation()
Finds the orientation of a text line in an image. The text line is assumed to be darker than the background
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region where the text line is located |
image |
CONST_OBJECT Image |
Input sample |
charHeightPix |
INT |
Character height |
orientationFromRad |
FLOAT |
Start of search interval |
orientationToRad |
FLOAT |
End of search interval |
| Name | Type | Description |
|---|---|---|
orientationAngleRad |
FLOAT |
Orientation of text line in radians |
local orientationAngleRad = Image.OCR.Halcon.findTextLineOrientation(region, image, charHeightPix, orientationFromRad, orientationToRad)
rotateImage()
Rotates an image.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Input image |
orientationAngleRad |
FLOAT |
Orientation of text line in radians |
| Name | Type | Description |
|---|---|---|
rotatedImage |
OBJECT Image |
The rotated image |
local rotatedImage = Image.OCR.Halcon.rotateImage(image, phi)
Image.OCR.Halcon.AutoSegmenter
Automatically segments text in an image.
Overview
Functions
create()
Creates an instance of a OCR.Halcon.AutoSegmenter.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the AutoSegmenter. |
handle = Image.OCR.Halcon.AutoSegmenter.create()
findText()
Segments an image into text lines and characters.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the configuration. |
image |
CONST_OBJECT Image |
Input sample |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the find text operation is only performed within the bounding box of is region. This can save a lot of computation time if the region is small. |
| Name | Type | Description |
|---|---|---|
textLines |
Result with found text lines. |
local textLines = Image.OCR.Halcon.AutoSegmenter.findText(handle, image)
setParameter()
Sets a parameter used to help/guide the automatic segmentation of the image into text lines.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the configuration. |
paramName |
Name of parameter. |
|
paramValue |
AUTO |
Flexible parameter to set a segmentation parameter. Could be a string, an integer value or a float value. |
Image.OCR.Halcon.AutoSegmenter.setParameter(handle, paramName, paramValue)
Image.OCR.Halcon.FontClassifier
Classifies text in an image using a pre-trained font classifier.
Overview
Functions
classifyCharacters()
Finds characters in one text line. The text line must first be segmented into individual characters and supplied as a vector of pixelregions.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the configuration. |
textline |
CONST_OBJECT Image.PixelRegion |
Array of pixel regions each containing a text character |
image |
CONST_OBJECT Image |
Image with text |
expression |
STRING |
Regular expression (Perl Compatible Regular Expressions) defining the allowed set of characters |
| Name | Type | Description |
|---|---|---|
characters |
STRING |
Classified characters. If the used fonts has a rejection class (name ends with _REJ) the ASCII code \x1A is returned whenever a character can not be classified |
confidence |
FLOAT |
The confidence for each found character |
regExpScore |
FLOAT |
The score for how well the found characters match the regular expression. Set to 1.0 if no expression is used. |
local characters, confidence, regExpScore = Image.OCR.Halcon.FontClassifier.classifyCharacters(handle, textline, image, expression)
create()
Creates an instance of a OCR.Halcon.FontClassifier
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the FontClassifier. |
handle = Image.OCR.Halcon.FontClassifier.create()
setFont()
Set which pre-trained font classifier to used. Font names ending with _Rej have a rejection class. With fonts that provide a rejection class, it is possible to distinguish characters from background clutter. Fonts with a rejection class return the ASCII Code 26, which is SUB (substitute) if no letter was found.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the configuration. |
fontName |
ENUM PreTrainedFonts |
Name of pre-trained font. Default value: 'INDUSTRIAL_REJ' |
Image.OCR.Halcon.FontClassifier.setFont(handle, mode, fontName)
Image.OCR.Halcon.ManualSegmenter
Segments text in an image based on user input.
Overview
Functions
create()
Creates an instance of a OCR.Halcon.ManualSegmenter.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the ManualSegmenter. |
handle = Image.OCR.Halcon.ManualSegmenter.create()
findText()
Segments an image into text lines and characters.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the configuration. |
image |
CONST_OBJECT Image |
Input sample |
region |
CONST_OBJECT Image.PixelRegion |
Optional region of interest. If supplied, the filter operation is only performed within the bounding box of is region. This can save a lot of computation time if the region is small. |
| Name | Type | Description |
|---|---|---|
textLines |
Result with found text lines. |
local textLines = Image.OCR.Halcon.ManualSegmenter.findText(handle, image)
setParameter()
Sets a parameter used when segmenting the image for text lines.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the configuration. |
paramName |
Name of parameter. |
|
paramValue |
AUTO |
Flexible parameter to set a segmentation parameter. Could be a string, an integer value or a float value. |
Image.OCR.Halcon.ManualSegmenter.setParameter(handle, paramName, paramValue)
Image.OCR.Halcon.SegmenterResult
Segmentation result from either the ManualSegmenter or the AutoSegmenter. Contains all found text lines. Each text line is stored as a vector of PixelRegions.
Overview
Functions
getNumberOfTextLines()
Returns the number of found text lines.
| Name | Type | Description |
|---|---|---|
result |
CONST_OBJECT Image.OCR.Halcon.SegmenterResult |
The segmentation result to use. |
| Name | Type | Description |
|---|---|---|
numTextLines |
INT |
The number of text lines. |
numTextLines = Image.OCR.Halcon.SegmenterResult.getNumberOfTextLines(result)
getTextLine()
Returns the text line with the given index.
| Name | Type | Description |
|---|---|---|
result |
CONST_OBJECT Image.OCR.Halcon.SegmenterResult |
The segmentation result to use. |
index |
INT |
Index of the text line. |
| Name | Type | Description |
|---|---|---|
textLine |
OBJECT Image.PixelRegion |
The text line as a vector of PixelRegions. |
textLine = Image.OCR.Halcon.SegmenterResult.getTextLine(result, index)
Image.PixelRegion
A PixelRegion represents a collection of pixels in an image. A common use-case is to represent regions or masks in an image and the underlying representation is therefore run-length coded in form of a list of connected row-segments. This makes the representation computationally efficient to work with. The pixels in a PixelRegion need not be connected though, but can consist of isolated pixels or a set of connected regions. It is assumed that a PixelRegion is used together with an Image object in which it defines the collection of pixels. The PixelRegion therefore knows only about pixel coordinates and is not aware of the Image object’s world coordinate system. For measurements inside the given PixelRegion or for transformations of the PixelRegion requiring the Image world coordinate system, the reference Image object must also be supplied as parameter to the corresponding functions. The PixelRegion can be obtained as a rasterized Shape object, but there is currently no function for converting a PixelRegion to a Shape object. A PixelRegion can be generated from an Image object, for example through a threshold operation, and it is possible to render a PixelRegion back into an Image object.
Overview
contains(), countBorderPixels(), countHoles(), countPixels(), createCircle(), createEmpty(), createFromPoints(), createRectangle(), dilate(), downsample(), erode(), fillHoles(), fillRegion(), fillRegionInplace(), findConnected(), getArea(), getBorderRegion(), getBoundingBox(), getBoundingBoxOriented(), getCenterOfGravity(), getCircularity(), getCompactness(), getConvexHull(), getConvexity(), getDifference(), getElongation(), getHistogram(), getIntersection(), getMedian(), getPercentiles(), getPerimeterLength(), getPrincipalAxes(), getStatistics(), getUnion(), getVolume(), intersectImage(), invert(), isEmpty(), thin(), toImage(), toPoints2D(), toPoints3D(), toString(), touchesImageBorder(), transform()
Functions
contains()
Return true if the region(s) contains the given point. If more than one region is provided true is returned if the point is inside any of the regions. If more than one point is provided an array is returned with one value for each input point.
included, inside
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region(s) |
point |
CONST_OBJECT Point |
Input point(s) |
| Name | Type | Description |
|---|---|---|
result |
BOOL |
True if the point is within the region(s), otherwise false |
result = Image.PixelRegion.contains(region, point)
countBorderPixels()
Return the number of border pixels of the region. A border pixel is located within the region and with neighboring pixels outside the region. 4-connectivity is used for the neighbor relation.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
| Name | Type | Description |
|---|---|---|
pixelCount |
INT |
Computed number of border pixels (single value or list) |
pixelCount = Image.PixelRegion.countBorderPixels(region)
countHoles()
Return the number of holes in the region. To avoid including very small holes that only represent image noise, consider performing a dilate operation before calling countHoles.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
| Name | Type | Description |
|---|---|---|
holeCount |
INT |
Computed number of holes (single value or list) |
holeCount = Image.PixelRegion.countHoles(region)
countPixels()
Return the number of pixels within the region.
area
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
| Name | Type | Description |
|---|---|---|
pixelCount |
INT |
Computed number of pixels (single value or list) |
pixelCount = Image.PixelRegion.countPixels(region)
createCircle()
Create a pixel region containing all pixels within the given circle. By providing vectors of centers and radii several pixel regions can be created. All vectors must be of equal length.
| Name | Type | Description |
|---|---|---|
center |
CONST_OBJECT Point |
Circle center. Can also be a vector to create several regions. |
radius |
FLOAT |
Circle radius. Can also be a vector to create several regions. |
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
The created pixel region, or vector of pixel regions for vector input. |
region = Image.PixelRegion.createCircle(Point.create(100,100), 20)
createEmpty()
Create an empty region.
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
The created empty pixel region. |
region = Image.PixelRegion.createEmpty()
createFromPoints()
Create a PixelRegion from a set of 2D points defined in image world coordinates. Any points outside the reference image bounds are ignored. By default, each point sets one pixel in the output region. The region point size can be adjusted by the pointDiameter parameter.
toPixelRegion
| Name | Type | Description |
|---|---|---|
points |
CONST_OBJECT Point |
List of world coordinates, represented as 2D Point objects, for each pixel in the region. |
referenceImage |
CONST_OBJECT Image |
Reference image, defines the image world coordinate system. |
pointDiameter |
INT |
Diameter of the points to create, in pixels. Point diameter must be odd and positive. Optional, default is one. |
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
The generated pixel region |
region = Image.PixelRegion.createFromPoints(points, referenceImage, pointDiameter)
createRectangle()
Create a pixel region containing all pixels within a rectangle with upper-left corner (x0,y0) and lower-right corner (x1,y1). By providing vectors of corners several pixel regions can be created. All vectors must be of equal length.
| Name | Type | Description |
|---|---|---|
x0 |
INT |
x0 (upper-left). Can also be a vector to create several regions. |
y0 |
INT |
y0 (upper-left). Can also be a vector to create several regions. |
x1 |
INT |
x1 (lower-right). Can also be a vector to create several regions. |
y1 |
INT |
y1 (lower-right). Can also be a vector to create several regions. |
| Name | Type | Description |
|---|---|---|
region |
OBJECT Image.PixelRegion |
The created pixel region, or vector of pixel regions for for vector input. |
region3 = Image.PixelRegion.createRectangle(x0, y0, x1, y1)
dilate()
Dilate the input region with a disc of the given pixel diameter.
morphology, expand
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or list of regions. |
diameter |
INT |
Disc diameter in pixels (must be odd). |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
Dilated region or list of regions, or nil on error. |
outputRegion = Image.PixelRegion.dilate(region, diameter)
downsample()
Downsample the pixel region(s) by an integer factor, keeping only rows and columns with coordinates equal to n*factor, where n = 0,1,2,…
| Name | Type | Description |
|---|---|---|
inputRegion |
CONST_OBJECT Image.PixelRegion |
Input region(s). |
factor |
INT |
Downsample factor. Must be larger than zero. |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
Input region(s) downsampled by the provided factor. |
outputRegion = Image.PixelRegion.downsample(inputRegion, 2)
erode()
Erode the input region with a disc of the given pixel diameter.
morphology, shrink
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or list of regions. |
diameter |
INT |
Disc diameter in pixels (must be odd). |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
Eroded region or list of regions, or nil on error. |
outputRegion = Image.PixelRegion.erode(region, diameter)
fillHoles()
Fill any holes in a region.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region. |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
Output region, where any holes in the input region has been filled. |
outputRegion = Image.PixelRegion.fillHoles(region)
fillRegion()
Set all pixels within the given region(s) in the target image to a specific value in world coordinates. The pixels outside the input region keep their original values. A new image with updated values is returned, and the input image is left unchanged. Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. If the value parameter is outside the image value range it will be clamped to the closest valid value. The output image inherits the image world coordinate system of the input image. Missing data handling: The missing data flag is kept in the output image, but the pixels in the fill region will be updated with non missing data.
inpaint, flood
Image.PixelRegion.fillHoles, Image.PixelRegion.fillRegionInplace, Image.drawPixelRegion, Image.replace, Image.fillRegion
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
The region(s) to fill. |
value |
FLOAT |
World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image. |
inputImage |
CONST_OBJECT Image |
Input image. |
| Name | Type | Description |
|---|---|---|
outputImage |
OBJECT Image |
Result image or nil if operation failed. |
outputImage = Image.PixelRegion.fillRegion(region, value, inputImage)
fillRegionInplace()
Inplace version of the Image.PixelRegion.fillRegion function that modifies the input image. See base function for full documentation.
inpaint, flood
Image.PixelRegion.fillHoles, Image.PixelRegion.fillRegionInplace, Image.drawPixelRegion, Image.replace, Image.fillRegion
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
The region(s) to fill. |
value |
FLOAT |
World coordinate value to set for pixels within the region. A vector with three values must be given if the input image is an RGB image. |
image |
OBJECT Image |
The image. This image is overwritten with the result image. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Reference to the result image. |
result = Image.PixelRegion.fillRegionInplace(region, value, image)
findConnected()
Find the connected components of an input pixel region, i.e., splits a PixelRegion object into a list of separated regions. Only keeps regions with a size (counted in number of pixels) within the range [minSize, maxSize].
blob extraction, labeling, connected components
| Name | Type | Description |
|---|---|---|
inputRegions |
CONST_OBJECT Image.PixelRegion |
Input region(s) |
minSize |
INT |
Minimum output region size |
maxSize |
INT |
Maximum output region size |
maxRegionCount |
INT |
Maximum number of output regions to return (default is 1000). Used to limit the memory requirements of the algorithm. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image.PixelRegion |
List of connected components represented as pixel regions, sorted by decreasing size |
regions = Image.PixelRegion.findConnected(inputRegion, 10)
getArea()
Return the area of the specified region. This is equal to the number of pixels in the region times the area of each pixel as specified by the pixel sizes in the x,y-dimensions. Missing data handling: Any missing data information of the referenceImage is ignored. The area is calculated purely on the pixelRegion and scaled using the pixel scale of the image world coordinate system.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
referenceImage |
CONST_OBJECT Image |
Reference image, defining the image world coordinate system. |
| Name | Type | Description |
|---|---|---|
area |
FLOAT |
Region area or areas in world units |
area = Image.PixelRegion.getArea(region, referenceImage)
getBorderRegion()
Get the border pixels of the input region as a new pixel region. Border pixels are pixels within the input region bordering to pixels outside the region.
edge, perimeter
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or list of regions |
| Name | Type | Description |
|---|---|---|
borderRegion |
OBJECT Image.PixelRegion |
Output border region or list of regions |
outputRegion = Image.PixelRegion.getBorderRegion(region)
getBoundingBox()
Return an axis-aligned box of the region as a rectangle Shape in image world coordinates. To get the bounding box in pixel coordinates instead, just omit the optional referenceImage parameter.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list. |
referenceImage |
CONST_OBJECT Image |
Reference image, defining the image world coordinate system. |
| Name | Type | Description |
|---|---|---|
box |
OBJECT Shape |
Bounding box, represented as a rectangle Shape object, always with zero rotation (single box or list). |
box = Image.PixelRegion.getBoundingBox(region)
getBoundingBoxOriented()
Returns the rectangle (not necessarily axis-aligned) of minimum area containing the object. The area is computed in world coordinates. The rectangle is oriented such that the width is larger or equal to the height and with the orientation angle in the range (0..PI).
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
referenceImage |
CONST_OBJECT Image |
Reference image, used to define the image world coordinate system |
accuracyRad |
FLOAT |
Required accuracy of the rotation (maximal error of the reported rotation, in radians). Affects both accuracy and speed. |
| Name | Type | Description |
|---|---|---|
rectangle |
OBJECT Shape |
The computed oriented bounding box, represented as a rectangle Shape object (single object or list) |
rectangle = Image.PixelRegion.getBoundingBoxOriented(region, referenceImage)
getCenterOfGravity()
Return the center of gravity of the region in image world coordinates. Missing data handling: Any missing data information of the referenceImage is ignored. The center of gravity is calculated purely on the pixelRegion compensated for image scale and origin.
cog
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
referenceImage |
CONST_OBJECT Image |
Reference image, defining the image world coordinate system |
| Name | Type | Description |
|---|---|---|
point |
OBJECT Point |
Center of gravity represented as a 2D Point object (single point or list of points) |
point = Image.PixelRegion.getCenterOfGravity(region, referenceImage)
getCircularity()
Returns a circularity measure that is 1.0 for ideal circles and smaller for other shapes. The measure is robust to high-frequency noise like jagged edges along the circle perimeter, so even noisy circles get a measure close to 1.0. The measure is significantly lower if the overall appearance is rather an ellipse, square or other non-circular shape.
roundness
Image.PixelRegion.getConvexity, Image.PixelRegion.getConvexity, Image.PixelRegion.getCompactness
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
| Name | Type | Description |
|---|---|---|
circularity |
FLOAT |
The computed circularity measure (single value or list) |
circularity = Image.PixelRegion.getCircularity(region)
getCompactness()
Returns the compactness measure of the region (4 * PI * Area / Perimeter^2). This is close to 1.0 for circles and smaller for less compact regions.
roundness
Image.PixelRegion.getConvexity, Image.PixelRegion.getConvexity, Image.PixelRegion.getCircularity
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
referenceImage |
CONST_OBJECT Image |
Reference image, used to define the image world coordinate system |
| Name | Type | Description |
|---|---|---|
compactness |
FLOAT |
The computed compactness measure (single value or list) |
compactness = Image.PixelRegion.getCompactness(region, referenceImage)
getConvexHull()
Get the convex hull of the input pixel region.
| Name | Type | Description |
|---|---|---|
sourceRegion |
CONST_OBJECT Image.PixelRegion |
Input region or list of regions |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
Target region or list of regions, convex hull of the input |
outputRegion = Image.PixelRegion.getConvexHull(sourceRegion)
getConvexity()
Returns the convexity measure of the region (region area divided by area of convex hull). This is 1.0 for convex regions and smaller the more non-convex the region is
Image.PixelRegion.getCircularity, Image.PixelRegion.getConvexHull, Image.PixelRegion.getConvexity, Image.PixelRegion.getCompactness
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
| Name | Type | Description |
|---|---|---|
convexity |
FLOAT |
The computed convexity measure (single value or list) |
convexity = Image.PixelRegion.getConvexity(region)
getDifference()
Get the set difference of the input regions. Returns a new region containing all pixels present in the first region but not in the second. If two regions are give, the function returns the difference of the two regions. If one list and one region is given, the function returns a list of regions containing the differences of each region in the list and the single region. If two lists are given, the function returns a list of regions containing the pair-wise difference of the regions in the lists. The lists must be the same length.
Image.PixelRegion.getDifference, Image.PixelRegion.intersectImage, Image.PixelRegion.getUnion
| Name | Type | Description |
|---|---|---|
region1 |
CONST_OBJECT Image.PixelRegion |
First input region, or list of regions |
region2 |
CONST_OBJECT Image.PixelRegion |
Second input region, or list of regions |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
Resulting region or list of regions |
outputRegion = Image.PixelRegion.getDifference(region1, region2)
getElongation()
Get the elongation of the region, defined as the ratio between the principal axes lengths. This measure is also often called eccentricity. The value is 1.0 for circles larger than 1.0 for regions that are elongated in one direction.
eccentricity
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
referenceImage |
CONST_OBJECT Image |
Reference image, used to define the image world coordinate system |
| Name | Type | Description |
|---|---|---|
elongation |
FLOAT |
Computed elongation measure (single value or list) |
elongation = Image.PixelRegion.getElongation(region, referenceImage)
getHistogram()
Get a histogram of the image values within the specified region. If the image supports missing data, pixels marked as missing are not included in the histogram. If a pixel-world mapping is specified, the histogram is computed using world coordinates. If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. Optionally, a reference surface in world coordinates may be provided, in which case the histogram is based on deviations from the reference surface. The default surface is the plane z=0. See also Image.getHistogram.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Region specifying which parts of the image to include in the histogram |
image |
CONST_OBJECT Image |
Input image, specifying values to use in the histogram |
binCount |
INT |
Number of bins. Uses 32 bins as default. |
minValue |
FLOAT |
Minimum of the value range to cover. Uses an automatic range if omitted. |
maxValue |
FLOAT |
Maximum of the value range to cover. Uses an automatic range if omitted. |
referenceSurface |
CONST_OBJECT Shape3D |
Zero-reference surface for the histogram. Optional, default is the plane z=0. |
| Name | Type | Description |
|---|---|---|
histogram |
FLOAT |
Histogram, represented as a vector of floats |
binCenters |
FLOAT |
The center of each histogram bin in the input value range |
histogram, centers = Image.PixelRegion.getHistogram(region, image, 64)
getIntersection()
Get the set intersection of two regions. If two regions are give, the function returns the set intersection of the two regions. If one list and one region is given, the function returns a list of regions containing the intersections of each region in the list and the single region. If two lists are given, the function returns a list of regions containing the pair-wise intersection of the regions in the lists. The lists must be the same length.
Image.PixelRegion.getDifference, Image.PixelRegion.intersectImage, Image.PixelRegion.getUnion
| Name | Type | Description |
|---|---|---|
region1 |
CONST_OBJECT Image.PixelRegion |
First input region, or list of regions |
region2 |
CONST_OBJECT Image.PixelRegion |
Second input region, or list of regions, subtracted from region1 |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
Resulting region or list of regions |
outputRegion = Image.PixelRegion.getIntersection(region1, region2)
getMedian()
Get the median value of the pixels within the region, a special case of Image.PixelRegion.getPercentiles. The median is derived from a histogram and it is approximate. Optionally, a reference surface in world coordinates may be provided, in which case the deviations from the reference surface are considered. The default surface is the plane z=0.
percentile, statistics
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
image |
CONST_OBJECT Image |
Input image, defines the image from which to get pixel value input. |
referenceSurface |
CONST_OBJECT Shape3D |
Zero-reference 3D surface plane for pixel world coordinate values. Optional, default is the plane z=0. |
| Name | Type | Description |
|---|---|---|
median |
FLOAT |
The approximate median. |
median = Image.PixelRegion.getMedian(region, image, referenceSurface)
getPercentiles()
Get a set of rank measurement according to the specified percentile levels. Level 0.5 gives the median, level 0.9 give a value larger than 90% of all image pixels, etc. All values are derived from a histogram and are approximate. Optionally, a reference surface in world coordinates may be provided, in which case the deviations from the reference surface are considered. The default surface is the plane z=0.
statistics
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region |
image |
CONST_OBJECT Image |
Input image, defines the image from which to get pixel value input. |
percentileLevels |
FLOAT |
Percentile levels in the range (0..1) |
referenceSurface |
CONST_OBJECT Shape3D |
Zero-reference 3D surface plane for pixel world coordinate values. Optional, default is the plane z=0. |
| Name | Type | Description |
|---|---|---|
values |
FLOAT |
Output values |
values = Image.PixelRegion.getPercentiles(region, image, percentileLevels, referenceSurface)
getPerimeterLength()
Get the region perimeter length in world units. The length is computed as the sum of distances between individual pixels. Note that this means that the reported perimeters are different than the analytical perimeter for mathematical objects like circles and rectangles.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
referenceImage |
CONST_OBJECT Image |
Reference image, used to define the image world coordinate system. |
| Name | Type | Description |
|---|---|---|
perimeterLength |
FLOAT |
Computed perimeter length in world units (single value or list) |
perimeterLength = Image.PixelRegion.getPerimeterLength(region, referenceImage)
getPrincipalAxes()
Get principal axes of the region (orientation and length of major/minor axes, derived from region moments).
PCA, covariance, eccentricity, elongation, major, moment, minor
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region |
referenceImage |
CONST_OBJECT Image |
Reference image, defines the image world coordinate system. |
| Name | Type | Description |
|---|---|---|
angleRad |
FLOAT |
Rotation angle of the major axis in radians. |
majorAxisWorld |
FLOAT |
Length of the major axis in world units |
minorAxisWorld |
FLOAT |
Length of the minor axis in world units |
angleRad, majorAxisWorld, minorAxisWorld = Image.PixelRegion.getPrincipalAxes(region, referenceImage)
getStatistics()
Get pixel value statistics for pixels belonging to a pixel region. Image world coordinate system values are used and pixels with missing data are excluded. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided, basing the statistics on deviations from that surface. If the statistics can not be calculated, nil is returned. A vector of regions can be provided, in which case four vectors of statistics are returned, one entry for each input region. Any invalid input region in the vector will have the corresponding output entries set to zero.
average, max, maximum, min, minimum, standard deviation, std, mean
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region, defines the region of image in which to gather statistics, or several regions where statistics are calculated individually for each region. |
image |
CONST_OBJECT Image |
Input image, defines the image from which to get pixel value input. |
referenceSurface |
CONST_OBJECT Shape3D |
Reference surface, defines the zero level in world coordinates. Default is the plane z=0. |
| Name | Type | Description |
|---|---|---|
min |
FLOAT |
Minimal value, or vector of values with one entry for each region. |
max |
FLOAT |
Maximal value, or vector of values with one entry for each region. |
average |
FLOAT |
Average value, or vector of values with one entry for each region. |
standardDeviation |
FLOAT |
Standard deviation, or vector of standard deviations with one entry for each region. |
min, max, average, standardDeviation = Image.PixelRegion.getStatistics(region, image, referenceSurface)
getUnion()
Get the set union of two or more regions. If two regions are give, the function returns the set union of the two regions. If one list of regions is given, the function returns the set union of all regions in the list. If one list and one region is given, the function returns a list of regions containing the unions of each region in the list and the single region. If two lists are given, the function returns a vector of regions containing the pair-wise unions of the regions in the lists. The lists must be the same length.
| Name | Type | Description |
|---|---|---|
region1 |
CONST_OBJECT Image.PixelRegion |
First input region or list of regions |
region2 |
CONST_OBJECT Image.PixelRegion |
Second input region or list of regions |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
Resulting region or list of regions |
outputRegion = Image.PixelRegion.getUnion(region1, region2)
getVolume()
Get the volume between a height map and a reference surface within the region or regions. Image world coordinate system values are used. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided. NOTE: Values below the reference surface are disregarded (counted as a zero-volume-contribution). Pixels with missing data are disregarded (counted as a zero-volume-contribution). For other ways of handling missing data, such as filling using nearby data, call the appropriate Image.missingData-function before calling getVolume.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list. |
heightMap |
CONST_OBJECT Image |
Input image that can be interpreted as a height map using the origin and pixelSize properties. |
referenceSurface |
CONST_OBJECT Shape3D |
Reference surface, defines the zero level in world coordinates. Default is the plane z=0. |
| Name | Type | Description |
|---|---|---|
volume |
FLOAT |
The volume contained below the height map within the input region (single value or list), or nil in case of failure. |
volume = Image.PixelRegion.getVolume(region, heightMap)
intersectImage()
Get the part of a pixel region within a reference image.
complement, difference
Image.PixelRegion.getDifference, Image.PixelRegion.invert, Image.PixelRegion.getIntersection
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or list of regions. |
referenceImage |
CONST_OBJECT Image |
Reference image, defines the area for cropping the region. |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
The part of region or list of regions within referenceImage, or nil on error. |
outputRegion = Image.PixelRegion.intersectImage(region, referenceImage)
invert()
Get the complement within a reference image, returns a pixel region(s) containing all reference image pixels not in the input region(s).
complement
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region(s). |
referenceImage |
CONST_OBJECT Image |
Reference image, defines the area for inverting the region(s). |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
The complement(s) to region(s) within referenceImage, or nil on error. |
outputRegion = Image.PixelRegion.invert(region, referenceImage)
isEmpty()
Check if the region contains zero pixels. If a vector of pixel regions is provided the output is a vector of the same length.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input pixel region. Can also be a vector of pixel regions. |
| Name | Type | Description |
|---|---|---|
isEmpty |
BOOL |
True if the region is empty. Can also be a vector of booleans. |
isEmpty = Image.PixelRegion.isEmpty(region)
thin()
Creates a skeleton region out of the input region.
morphology, skeleton
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or list of regions. |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
Skeleton region |
outputRegion = Image.PixelRegion.thin(region)
toImage()
Convert the region to an image, using a specified value for pixels within the region. The value is in world coordinates and is clamped to the representable range of the image.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region |
referenceImage |
CONST_OBJECT Image |
Reference image, defines the size, pixel type and image world coordinate system of the output image. |
valueWorld |
FLOAT |
World coordinate value to use within the region, default is 255 |
| Name | Type | Description |
|---|---|---|
outputImage |
OBJECT Image |
Image containing the region |
outputImage = Image.PixelRegion.toImage(region, referenceImage, valueWorld)
toPoints2D()
Get a vector of the pixels contained in the region represented as 2D Point objects. Pixel coordinates are converted to image world coordinates using the reference image. Any parts of the input region that is outside the reference image bounds is ignored.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
The region to process |
referenceImage |
CONST_OBJECT Image |
Reference image, defines the image world coordinate system |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
Vector of 2D Point objects, expressed in image world coordinates, for each pixel contained within the region. |
points = Image.PixelRegion.toPoints2D(region, referenceImage)
toPoints3D()
Get a vector of the pixels contained in the region represented as 3D Point objects, including a z value from the reference image. Any parts of the input region that is outside the image bounds or contains missing data is ignored.
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
The region to process |
referenceImage |
CONST_OBJECT Image |
Input image, defines the pixel-world mapping and is used to get z values (pixel values converted using the z-part of the pixel-world mapping) |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
Vector of 3D Point objects, expressed in image world coordinates, for each pixel contained within the region. |
points = Image.PixelRegion.toPoints3D(region, referenceImage)
toString()
Get a brief string description of the pixel region. This is equal to the text shown in the debugger to describe the region. Can also be called with a vector of pixel regions.
description, help, print
| Name | Type | Description |
|---|---|---|
pixelRegion |
CONST_OBJECT Image.PixelRegion |
Input pixel region. Can also be a vector of pixel regions. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
Description of the region. If the input is a vector the output is a vector of strings. |
print("Description: " .. Image.PixelRegion.toString(pixelRegion))
touchesImageBorder()
Returns true if a pixel region touches the border of provided image
| Name | Type | Description |
|---|---|---|
region |
CONST_OBJECT Image.PixelRegion |
Input region or region list |
referenceImage |
CONST_OBJECT Image |
Input image, used only to define the image size |
| Name | Type | Description |
|---|---|---|
touches |
BOOL |
True if region touches image borders (single value or list) |
outputRegion = Image.PixelRegion.touchesImageBorder(region, referenceImage)
transform()
Transform the region using a general 2D Transform object, expressed in image world coordinates.
| Name | Type | Description |
|---|---|---|
inputRegion |
CONST_OBJECT Image.PixelRegion |
Input region, or a list of regions |
transform |
CONST_OBJECT Transform |
Transform to apply, expressed in world coordinates |
referenceImage |
CONST_OBJECT Image |
Reference image, used to define the image world coordinate system |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
The transformed pixel region or region list |
outputRegion = Image.PixelRegion.transform(region, transform, referenceImage)
Image.PixelRegion.Filter
Filter for pixel regions. Offers convenient filtering and sorting based on all features from Image.PixelRegion. The description of each filter contains a reference to the corresponding function.
Keywords
blobs, extraction, sorting, features
See also
Overview
Functions
apply()
Apply the filter to a region list. Return the filtered and sorted regions. The actual regions are copied by reference, so changing a region in the input list makes the same region change also in the output list and vice versa. Note that lists in Lua are 1-indexed and matrices are 0-indexed, so the features corresponding to filteredRegions[i] is at row i-1 in the featureValues matrix. If no blobs are found, the function returns an empty filteredRegions list and no featureValues matrix.
| Name | Type | Description |
|---|---|---|
filter |
OBJECT Image.PixelRegion.Filter |
Filter to apply |
inputRegions |
OBJECT Image.PixelRegion |
Input regions |
inputImage |
OBJECT Image |
Input image, used for pixel-world mapping and for pixel values if value statistics features are used (median, average, etc.) |
| Name | Type | Description |
|---|---|---|
filteredRegions |
OBJECT Image.PixelRegion |
Filtered and sorted output regions |
featureValues |
OBJECT Matrix |
Matrix of computed feature values. Each row corresponds to an output region and each column to a computed feature. The columns are in the same order as the features are mentioned in calls to setRange and setCondition before applying the filter. |
filteredRegions, featureValues = Image.PixelRegion.Filter.apply(filter, inputRegions, inputImage)
create()
Create a new PixelRegion filter
| Name | Type | Description |
|---|---|---|
filter |
OBJECT Image.PixelRegion.Filter |
The new filter |
filter = Image.PixelRegion.Filter.create()
setCondition()
Set a new equality/inequality condition to the filter. Only regions with feature value within the given range will be included in the filter output.
inequal, equal
| Name | Type | Description |
|---|---|---|
filter |
OBJECT Image.PixelRegion.Filter |
Input filter to modify |
featureType |
ENUM FeatureType |
The feature type that the filter applies to. Must be an integer feature type. |
exactValue |
INT |
Exact value to compare to |
equality |
BOOL |
Set to true for equality comparison and false for inequality. Default is equality. |
Image.PixelRegion.Filter.setCondition(filter, "HOLESCOUNT", 0)
setRange()
Set a new range constraint to the filter. Only regions with feature value within the given range will be included in the filter output.
interval
| Name | Type | Description |
|---|---|---|
filter |
OBJECT Image.PixelRegion.Filter |
Input filter to modify |
featureType |
ENUM FeatureType |
The feature type that the filter applies to |
minValue |
FLOAT |
Minimum allowed value (inclusive) |
maxValue |
FLOAT |
Maximum allowed value (inclusive) |
withinRange |
BOOL |
Set to true to setup a within-range check and false for an outside-range check. Default is within-range. |
Image.PixelRegion.Filter.setRange(filter, "CONVEXITY", 0.0, 0.8)
sortBy()
Defines which feature the output list shall be sorted by
| Name | Type | Description |
|---|---|---|
filter |
OBJECT Image.PixelRegion.Filter |
Input filter to modify |
featureType |
ENUM FeatureType |
The feature type to sort by |
ascending |
BOOL |
Set to true to sort in ascending order (default), false for descending |
Image.PixelRegion.Filter.sortBy(filter, "CENTROIDX")
toString()
Get a user-friendly string description of the filter
| Name | Type | Description |
|---|---|---|
filter |
OBJECT Image.PixelRegion.Filter |
Input filter |
| Name | Type | Description |
|---|---|---|
description |
STRING |
User-friendly description of the filter |
print("The filter is: " .. Image.PixelRegion.Filter.toString(filter))
Image.Provider
Provides functionality to control and receive heightmap images from the camera of the programmable device.
Overview
Image.Provider.Camera
Provides functionality to control and receive images from the camera of the programmable device.
Functions
create()
Creates an instance of the image provider, which provides images asynchronously. Will return nil if there already exists a handle of this CROWN.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
ImageProviderCam exists as long as this handle. |
handle = Image.Provider.Camera.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
register()
This function is used to register for any event of this provider. The event name is specified as parameter.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle returned by create |
eventname |
STRING |
The event to register to |
callback |
STRING |
name of function to call upon the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
Image.Provider.Camera.register(handle, "OnNewImage", "HandleNewImage")
setConfig()
Applies the given configuration to the camera provider. Can cause minor errors if called during active image acquisition.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the Camera provider. |
configHandle |
HANDLE |
Handle of config instance to apply. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
true if new value could be set in configuration |
Image.Provider.Camera.setConfig(camHandle, configHandle)
start()
Triggers the camera to start taking images explicitly.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle returned by create |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if call to start succeeded and image acquisition was started. |
Image.Provider.Camera.start(handle)
stop()
Stops taking images explicitly.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle returned by create |
Image.Provider.Camera.stop(handle)
trigger()
Trigger images explicitly. Image trigger mode must be set to "SOFTWARE" by Image.Provider.Camera.V3TConfig3D.setImageTriggerMode().
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
abortOngoing |
BOOL |
If true any ongoing image acquisition is aborted before triggering. Default set to false |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.trigger(handle, true)
Events
OnNewImage
The image event which is thrown for every image.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle returned by create |
image |
OBJECT Image |
the captured image |
sensorData |
OBJECT SensorData |
additional data belonging to the image |
Image.Provider.Camera.V3TConfig2D
Configuration for acquiring 2D sensor images. The sensor image is useful for viewing the apperance of the laser while configuring exposure and gain. Sensor images can also be used for 2D image analysis after disabling the laser with TriSpector.setLaserEnabled(false). Call Image.Provider.Camera.setConfig() with a V3TConfig2D to activate sensor image acquisition.
Overview
Functions
create()
Creates an instance of a V3TConfig2D.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance. |
handle = Image.Provider.Camera.V3TConfig2D.create()
getExposureTime()
Get exposure time
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
exposureTime |
INT |
Returns configured exposure time in microseconds |
exposureTime = Image.Provider.Camera.V3TConfig2D.getExposureTime(handle)
getGain()
Get gain
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
gain |
FLOAT |
Returns configured gain |
gain = Image.Provider.Camera.V3TConfig2D.getGain(handle)
getImageTriggerMode()
Get image trigger mode
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
imageTriggerMode |
ENUM ImageTriggerMode |
Returns configured image trigger mode |
imageTriggerMode = Image.Provider.Camera.V3TConfig2D.getImageTriggerMode(handle)
getSensorRegion()
Get sensor region
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
width |
INT |
Width in pixels |
height |
INT |
Height in pixels |
xOffset |
INT |
X-offset in pixels |
yOffset |
INT |
Y-offset in pixels |
width, height, xOffset, yOffset = Image.Provider.Camera.V3TConfig2D.getSensorRegion(handle)
setExposureTime()
Set exposure time
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
exposureTime |
INT |
Exposure time in microseconds. Allowed range [1, 100000] |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig2D.setExposureTime(handle, 50)
setGain()
Set gain
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
gain |
FLOAT |
Gain. Allowed range [1, 8] |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig2D.setGain(handle, 2.0)
setImageTriggerMode()
Determines how sensor images are triggered.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
imageTriggerMode |
ENUM ImageTriggerMode |
Image trigger mode |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig2D.setImageTriggerMode(handle, "SOFTWARE")
setSensorRegion()
Set the region on the image sensor to use when acquiring 2D-images.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
width |
INT |
Width in pixels. Allowed range [64, 1280] |
height |
INT |
Height in pixels. Allowed range [24, 1024] |
xOffset |
INT |
X-offset in pixels. Allowed range [0, 1280 - width] |
yOffset |
INT |
Y-offset in pixels. Allowed range [0, 1024 - height] |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig2D.setSensorRegion(handle, 1280, 1024, 0, 0)
validate()
Validate the configuration settings of this V3TConfig2D. This allows testing the validity of a V3TConfig2D without setting it to a provider. Note that Image.Provider.Camera.setConfig rejects invalid instances.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
validConfig |
BOOL |
Returns true if the configuration settings are valid, otherwise false |
valid = Image.Provider.Camera.V3TConfig2D.validate(handle)
Image.Provider.Camera.V3TConfig3D
Configuration for acquiring heightmaps. Call Image.Provider.Camera.setConfig() with a V3TConfig3D to activate heightmap acquisition.
Overview
create(), get2DConfig(), getEncoderTicksPerMm(), getExposureTime(), getExposureTimeLimits(), getFieldOfView(), getFreeRunningSpeed(), getFreeRunningSpeedLimits(), getGain(), getGuaranteedFieldOfView(), getHeightmapLength(), getHeightmapLengthLimits(), getImageTriggerDelay(), getImageTriggerMode(), getLaserThreshold(), getObjectTriggerLine(), getPeakSelectionMode(), getProfileDistance(), getProfileDistanceLimits(), getProfileTriggerMode(), getXResolution(), getXResolutionLimits(), setEncoderTicksPerMm(), setExposureTime(), setFieldOfView(), setFreeRunningSpeed(), setGain(), setHeightmapFinishedOutput(), setHeightmapLength(), setImageTriggerDelay(), setImageTriggerMode(), setLaserThreshold(), setObjectTriggerLine(), setPeakSelectionMode(), setProfileDistance(), setProfileTriggerMode(), setXResolution(), validate()
Functions
create()
Creates an instance of a V3TConfig3D.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance. |
handle = Image.Provider.Camera.V3TConfig3D.create()
get2DConfig()
Get a V3TConfig2D with the sensor settings from this V3TConfig3D. The V3TConfig2D can be used to acquire 2D sensor images for inspecting the appearance of the laser line. The V3TConfig2D sensor region is determined by the V3TConfig3D field of view.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
configHandle |
HANDLE |
Handle of a 2D config instance |
config = Image.Provider.Camera.V3TConfig3D.get2DConfig(handle)
getEncoderTicksPerMm()
Get the configured number of encoder ticks per mm. A tick is defined as a complete cycle of an encoder channel.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
ticksPerMm |
FLOAT |
Returns configured encoder ticks per mm |
ticksPerMm = Image.Provider.Camera.V3TConfig3D.getEncoderTicksPerMm(handle)
getExposureTime()
Get the configured exposure time.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
exposureTime |
INT |
Returns configured exposure time in microseconds |
exposureTime = Image.Provider.Camera.V3TConfig3D.getExposureTime(handle)
getExposureTimeLimits()
Get the current limits for setExposureTime. The upper limit depends on the field of view size.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
min |
INT |
Minimum possible exposure time |
max |
INT |
Maximum possible exposure time |
min, max = Image.Provider.Camera.V3TConfig3D.getExposureTimeLimits(handle)
getFieldOfView()
Get the configured field of view.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
width |
FLOAT |
Width in mm |
height |
FLOAT |
Height in mm |
xOffset |
FLOAT |
X-offset in mm for the field of view center relative to the guaranteed field of view center. |
zOffset |
FLOAT |
Z-offset in mm for the field of view center relative to the guaranteed field of view center. |
width, height, xOffset, zOffset = Image.Provider.Camera.V3TConfig3D.getFieldOfView(handle)
getFreeRunningSpeed()
Get the configured movement speed for free running profile trigger mode.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
freeRunningSpeed |
FLOAT |
Returns configured motion speed for free running mode in mm/s |
speed = Image.Provider.Camera.V3TConfig3D.getFreeRunningSpeed(handle)
getFreeRunningSpeedLimits()
Get the current limits for setFreeRunningSpeed. The upper limit depends on the profile distance, the field of view size and (in some cases) the exposure time.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
min |
FLOAT |
Minimum possible free running speed |
max |
FLOAT |
Maximum possible free running speed |
min, max = Image.Provider.Camera.V3TConfig3D.getFreeRunningSpeedLimits(handle)
getGain()
Get the configured image sensor gain.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
gain |
FLOAT |
Returns configured gain |
gain = Image.Provider.Camera.V3TConfig3D.getGain(handle)
getGuaranteedFieldOfView()
Get the guaranteed field of view. Working within this field of view guarantees that the configuration can be moved to another TriSpectorP device of the same variant. Returns nil if an invalid device variant is specified.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
deviceVariant |
Device variant to get guaranteed Field Of View for. Defaults to the executing device’s variant if not specified |
| Name | Type | Description |
|---|---|---|
lowerWidth |
INT |
Lower width in mm |
upperWidth |
INT |
Upper width in mm |
height |
INT |
Height in mm |
xOffset |
INT |
X-offset in mm |
zOffset |
INT |
Z-offset in mm |
lowerWidth, upperWidth, height, xOffset, zOffset = Image.Provider.Camera.V3TConfig3D.getGuaranteedFieldOfView(handle)
getHeightmapLength()
Get the configured heightmap length.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
length |
FLOAT |
Length in mm |
length = Image.Provider.Camera.V3TConfig3D.getHeightmapLength(handle)
getHeightmapLengthLimits()
Get the current limits for setHeightmapLength. A heightmap must contain at least 16 and at most 2500 profiles. The number of profiles is determined by the heightmap length divided by the profile distance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
min |
FLOAT |
Minimum possible heightmap length in mm |
max |
FLOAT |
Maximum possible heightmap length in mm |
min, max = Image.Provider.Camera.V3TConfig3D.getHeightmapLengthLimits(handle)
getImageTriggerDelay()
Get the configured image trigger delay value and unit
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
delay |
INT |
Returns configured image trigger delay value |
unit |
Returns configured image trigger delay unit |
delay, unit = Image.Provider.Camera.V3TConfig3D.getImageTriggerDelay(handle)
getImageTriggerMode()
Get image trigger mode
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
imageTriggerMode |
ENUM ImageTriggerMode |
Returns configured image trigger mode |
imageTriggerMode = Image.Provider.Camera.V3TConfig3D.getImageTriggerMode(handle)
getLaserThreshold()
Get the configured laser threshold. Sensor image intensities above this threshold will be included when locating the laser peak.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
laserThreshold |
INT |
Returns configured laser threshold |
laserThreshold = Image.Provider.Camera.V3TConfig3D.getLaserThreshold(handle)
getObjectTriggerLine()
Return the line used for object triggering.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
line |
OBJECT Shape3D |
3D line segment. The line used in Object Trigger. |
threshold |
INT |
line, threshold = Image.Provider.Camera.V3TConfig3D.getObjectTriggerLine(handle)
getPeakSelectionMode()
Get peak selection mode
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
peakSelectionMode |
ENUM PeakSelectionMode |
Returns configured peak selection mode |
mode = Image.Provider.Camera.V3TConfig3D.getPeakSelectionMode(handle)
getProfileDistance()
Get the configured distance in mm between consecutive profiles in the heightmap. Note that this is the value as specified with setProfileDistance which may differ from the actual value when using an encoder.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
profileDistance |
FLOAT |
Returns configured distance in mm between consecutive profiles |
profileDistance = Image.Provider.Camera.V3TConfig3D.getProfileDistance(handle)
getProfileDistanceLimits()
Get the current limits for setProfileDistance. Using an encoder (ProfileTriggerMode "ENCODER"), the limits depend on the heightmap length. In free running mode the limits also depend on the free running speed, field of view size and (in some cases) the exposure time.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
min |
FLOAT |
Minimum possible profile distance |
max |
FLOAT |
Maximum possible profile distance |
min, max = Image.Provider.Camera.V3TConfig3D.getProfileDistanceLimits(handle)
getProfileTriggerMode()
Get profile trigger mode
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
profileTriggerMode |
ENUM ProfileTriggerMode |
Returns current profile trigger mode |
profileTriggerMode = Image.Provider.Camera.V3TConfig3D.getProfileTriggerMode(handle)
getXResolution()
Get the configured X-resolution
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
xResolution |
FLOAT |
Returns configured X-resolution in mm/px |
xResolution = Image.Provider.Camera.V3TConfig3D.getXResolution(handle)
getXResolutionLimits()
Get the current limits for setXResolution. The limits depend on the field of view width.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
min |
FLOAT |
Minimum possible x-resolution |
max |
FLOAT |
Maximum possible x-resolution |
min, max = Image.Provider.Camera.V3TConfig3D.getXResolutionLimits(handle)
setEncoderTicksPerMm()
Specify the number of ticks that are given by the encoder per mm. A tick is defined as a complete cycle of an encoder channel.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
ticksPerMm |
FLOAT |
Encoder ticks per mm. Allowed range [1, 10000] |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setEncoderTicksPerMm(handle, 58)
setExposureTime()
Set the exposure time for the image sensor. With optimal exposure time the laser appears as a gray line in sensor images. If the exposure is too high, the reflectance image will be saturated.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
exposureTime |
INT |
Exposure time in microseconds. Allowed range [1, 100000] |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setExposureTime(handle, 50)
setFieldOfView()
Set the field of view rectangle. Data outside the rectangle is excluded from heightmap profiles. A smaller field of view can allow a shorter profile distance or higher speed.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
width |
FLOAT |
Width in mm |
height |
FLOAT |
Height in mm |
xOffset |
FLOAT |
X-offset in mm for the field of view center relative to the guaranteed field of view center. |
zOffset |
FLOAT |
Z-offset in mm for the field of view center relative to the guaranteed field of view center. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setFieldOfView(handle, 200, 400, 0, 200)
setFreeRunningSpeed()
Set the movement speed of the object (or TriSpectorP device) for free running profile trigger mode. This is used with setProfileTriggerMode("FREE_RUNNING").
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
freeRunningSpeed |
FLOAT |
Speed in mm/s. Allowed range [1.0, 5000.0] |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setFreeRunningSpeed(handle, 1000.0)
setGain()
Set the image sensor gain. Note that adjusting the exposure with setExposureTime is preferred over gain when possible, as gain increases noise in images.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
gain |
FLOAT |
Gain. Allowed range [1, 8] |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setGain(handle, 2.0)
setHeightmapFinishedOutput()
Digital output that will be activated when a heightmap acquisition is completed. The given output is activated when the last profile of a heightmap is acquired. This can be used to synchronize the image acquisition with an external device. The output will remain active for the duration of the activation value configured in the Connector.DigitalOut.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
output |
AUTO |
A Connector.DigitalOut instance or nil |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false. |
Image.Provider.Camera.V3TConfig3D.setHeightmapFinishedOutput(handle, do4)
setHeightmapLength()
Set the heightmap length in mm. The length and profile distance determines the number of profiles in a heightmap.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
length |
FLOAT |
Length in mm |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false. |
Image.Provider.Camera.V3TConfig3D.setHeightmapLength(handle, 300)
setImageTriggerDelay()
Set the image trigger delay in either ms or mm. Heightmap acquisition is delayed by the configured time or distance after triggering.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
delay |
INT |
Image trigger delay value. Allowed range [0,10000] |
unit |
Unit for the specified delay value |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setImageTriggerDelay(handle, 15, "MM")
setImageTriggerMode()
Set image trigger mode. This determines how heightmap images are triggered.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
imageTriggerMode |
ENUM ImageTriggerMode |
Image trigger mode |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setImageTriggerMode(handle, "OBJECT")
setLaserThreshold()
Set laser threshold. Sensor image intensities above this threshold will be included when locating the laser peak. A high threshold value reduces noise in the resulting heightmap, while a low threshold makes it possible to detect weak laser peaks.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
laserThreshold |
INT |
Laser threshold. Allowed range [0, 255] |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setLaserThreshold(handle, 50)
setObjectTriggerLine()
Specify a line and threshold for ImageTriggerMode "OBJECT". A heightmap acquisition is triggered if the amount of data extending above the line is greater than threshold.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
line |
OBJECT Shape3D |
3D line segment. The line must be specified in the XZ plane so Y-coordinates should be set to 0. |
threshold |
INT |
Threshold in percent how much data should be above |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setObjectTriggerLine(handle, line, 20)
setPeakSelectionMode()
Set the peak selection mode. This determines how the laser line is detected and can help for handling reflections.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
peakSelectionMode |
ENUM PeakSelectionMode |
Peak selection mode |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setPeakSelectionMode(handle, "STRONGEST")
setProfileDistance()
Set distance in mm between consecutive profiles in the heightmap. Note that when the profileTriggerMode is set to ENCODER the actual value for profileDistance might be slightly adjusted since the number of encoder ticks between two profiles is rounded to the nearest integer.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
profileDistance |
FLOAT |
Distance in mm between consecutive profiles. Allowed range [0.01,10] |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setProfileDistance(handle, 2.0)
setProfileTriggerMode()
Set whether heightmap profiles are triggered at fixed intervals (time) or by encoder ticks (distance).
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
profileTriggerMode |
ENUM ProfileTriggerMode |
Profile trigger mode |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setProfileTriggerMode(handle, "FREE_RUNNING")
setXResolution()
Set the heightmap X-resolution in mm/pixel. To improve handling of rotated objects, set the x-resolution equal to the profile distance (square pixels).
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
xResolution |
FLOAT |
X-resolution in mm/px |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
Image.Provider.Camera.V3TConfig3D.setXResolution(handle, 0.8)
validate()
Validate the configuration settings of this V3TConfig3D. This allows testing the validity of a V3TConfig3D without setting it to a provider. Note that Image.Provider.Camera.setConfig rejects invalid instances.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
validConfig |
BOOL |
Returns true if the configuration settings are valid, otherwise false |
valid = Image.Provider.Camera.V3TConfig3D.validate(handle)
Image.Provider.Directory
Image provider which provides images periodically from the filesystem. Images can be in format PNG or BMP.
Overview
Functions
create()
Creates an instance of the image directory provider, which provides images asynchronously from file-system.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Image provider exists as long as this handle exists. |
dirProv = Image.Provider.Directory.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
register()
This function is used to register for any event of the image provider. The event name is specified as parameter.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this provider |
eventname |
STRING |
The event to register to |
callback |
STRING |
function name to call on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
Image.Provider.Directory.register(dirProv, "OnNewImage", "handleNewImage")
setAutoDeleteActive()
Sets auto-delete active. This means the image is deleted from the directory after load. Default is false.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this provider |
state |
BOOL |
If true the image file will be deleted after being loaded. |
Image.Provider.Directory.setAutoDeleteActive(dirProv, true)
setCycleTime()
Sets the pause between taking images in milli seconds.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this provider |
periodMs |
INT |
Period in [ms] between images. |
Image.Provider.Directory.setCycleTime(handle, 500)
setCyclicModeActive()
Sets cyclic-mode active. Default is true.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this provider |
state |
BOOL |
If false driver stops taking images if end of directory is reached. |
Image.Provider.Directory.setCyclicModeActive(dirProv, true)
setImagePoolSizeMB()
Limits the number of mega bytes which can be acquired by capturing images and used at the same time. Default is 20.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of the provider. |
size |
INT |
Size of the internal image pool in mega byte. |
Image.Provider.Directory.setImagePoolSizeMB(cam, 20)
setPath()
Sets the directory and file extension(s) for the image provider from which it reads images.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this provider |
path |
STRING |
Path to the file-system |
fileextensions |
STRING |
Supported file extensions (comma separated). |
recursive |
BOOL |
An optional flag whether to run through subdriectories also. |
Image.Provider.Directory.setPath(dirProv, ImageInputPath)
start()
Starts taking images.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this provider |
burst |
INT |
Leave empty or '0' for continuous acquisition. >0:=enable burst-mode with provided number of images. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
local success = Image.Provider.Directory.start(dirProv)
stop()
Stops taking images.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this provider |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if function call was successful, otherwise false |
local stopped = Image.Provider.Directory.stop(dirProv)
Events
OnNewImage
The image event which is thrown for every new image.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this provider |
image |
OBJECT Image |
The loaded image |
sensorData |
OBJECT SensorData |
Supplementary data which belongs to the image |
Image.Pyramid
A multiscale representation of an image. Each level in the pyramid contains an image that is downsampled a factor 2 relative to the preceding level. Level 0 of the ImagePyramid keeps the original image. There are two smoothing operators that can be used to avoid aliasing artifacts in the downsampled images: "LINEAR" and "GAUSSIAN". The default method is "LINEAR". A non-interpolating nearest neighbor method is also available, "NEAREST". The coarsest level cannot contain an image smaller than 16x16 pixels, levels below this size are not created even if more levels are specified upon ImagePyramid creation. For odd-sized images, the output size after downscaling is different for the "LINEAR" and "GAUSSIAN" cases: if the size N is odd, the output size is (N-1)/2 for "LINEAR" and "NEAREST" while it is (N+1)/2 for "GAUSSIAN". Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position when plotted on different pyramid levels. Values in z, both origin and pixel size, are copied directly from the input image. Missing data handling: When using "LINEAR" or "NEAREST" as the DownsamplingMethod missing data is handled. For linear interpolation, missing data will remain if all points in the interpolation neighborhood are missing. Otherwise the missing data value will be ignored and the output will be the linear interpolation of the valid neighbors. DownsamplingMethod "GAUSSIAN", currently does not support missing data. Hardware acceleration: Some devices have FPGA-support for the pyramid generation. It is possible to switch between the CPU and FPGA versions using the setProcessingUnit()-function. Please note that if the FPGA accelerator is busy the processing will fall-back to CPU processing. The processing may also fall-back to CPU for some unsupported configurations. The rounding done in the CPU and the FPGA version may differ slightly resulting in different values in the least significant bit of the generated pyramid levels.
Keywords
decimate, downsample, resample, scalespace, subsample, scale
See also
Overview
Functions
create()
Create an image pyramid. If no arguments are given an unintialized pyramid will be created, which can be populated at a later stage using the Image.Pyramid.generate() function.
| Name | Type | Description |
|---|---|---|
image |
CONST_OBJECT Image |
Optional: Source image. Supported image types depends on used device type. |
levelCount |
INT |
Optional: Desired number of pyramid levels. One level will be used for the original image, so to get at least one downscaled version the levelCount parameter must be larger than 1. Note that the created ImagePyramid may contain fewer levels as the coarsest level is limited to a side of minimum 16 pixels. |
method |
ENUM DownsamplingMethod |
Optional: The downsampling method, currently NEAREST, LINEAR or GAUSSIAN are available. Default is LINEAR. |
processingUnit |
ENUM ProcessingUnit |
Optional: Processing Unit to use (CPU, FPGA). Default is CPU. |
cloneData |
BOOL |
Optional: If set to true a cloned copy of the original input image is made in the pyramid object. If set to false a reference copy is made, which saves execution time and memory. Note however, any other change made later to the input image will then also affect the pyramid object. Default is true, i.e., to make a cloned copy. |
| Name | Type | Description |
|---|---|---|
pyramidImage |
OBJECT Image.Pyramid |
The created image pyramid. |
pyramidImage = Image.Pyramid.create(image, levelCount, "LINEAR", "CPU")
generate()
Generate pyramid levels for an existing image pyramid, replacing any existing data in the pyramid object. The function works inplace, i.e., the object is modified directly.
| Name | Type | Description |
|---|---|---|
pyramidImage |
OBJECT Image.Pyramid |
The image pyramid. |
image |
CONST_OBJECT Image |
Source image. Supported image types depends on used device type. |
levelCount |
INT |
Desired number of pyramid levels. One level will be used for the original image, so to get at least one downscaled version the levelCount parameter must be larger than 1. Note that the created ImagePyramid may contain fewer levels as the coarsest level is limited to a side of minimum 16 pixels. |
method |
ENUM DownsamplingMethod |
The downsampling method, currently NEAREST, LINEAR or GAUSSIAN are available. Default is LINEAR. |
processingUnit |
ENUM ProcessingUnit |
Optional: Processing Unit to use (CPU, FPGA). Default is CPU. |
cloneData |
BOOL |
Optional: If set to true a cloned copy of the original input image is made in the pyramid object. If set to false a reference copy is made, which saves execution time and memory. Note however, any other change made later to the input image will then also affect the pyramid object. Default is true, i.e., to make a cloned copy. |
| Name | Type | Description |
|---|---|---|
pyramidImage |
OBJECT Image.Pyramid |
Reference to the pyramid with generated pyramid levels, or nil if something goes wrong. Note that the function works inplace, modifying the object directly, the output is mainly for error checking. |
pyramidImage = Image.Pyramid.generate(pyramidImage, image, levelCount, "LINEAR", "CPU")
getImage()
Get the image at the specified pyramid level. 0 is the 'finest' level i.e. the original image. The return image is a deep copy of the level image
| Name | Type | Description |
|---|---|---|
pyramidImage |
CONST_OBJECT Image.Pyramid |
The image pyramid. |
level |
INT |
The pyramid level to grab the image from. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The image at the specified pyramid level. |
image = Image.Pyramid.getImage(pyramidImage, levelCount)
getLevelCount()
Get the number of pyramid levels.
| Name | Type | Description |
|---|---|---|
pyramidImage |
CONST_OBJECT Image.Pyramid |
The image pyramid. |
| Name | Type | Description |
|---|---|---|
levelCount |
INT |
The number of pyramid levels. |
levelCount = Image.Pyramid.getLevelCount(pyramidImage)
getProcessingUnit()
Get configured processing unit.
| Name | Type | Description |
|---|---|---|
pyramidImage |
OBJECT Image.Pyramid |
The image pyramid. |
| Name | Type | Description |
|---|---|---|
processingUnit |
ENUM ProcessingUnit |
Processing Unit to use (CPU, FPGA). |
processingUnit = Image.Pyramid.getProcessingUnit(pyramidImage)
resize()
Resizes an existing image pyramid in terms of the number of pyramid levels, i.e., the pyramid is extendend with more levels or levels are removed. The pyramid is updated inplace.
cut, remove, extend
| Name | Type | Description |
|---|---|---|
pyramidImage |
OBJECT Image.Pyramid |
The image pyramid. |
levelCount |
INT |
The new number of pyramid levels. One level will be used for the original image, so to get at least one downscaled version the levelCount parameter must be larger than 1. Note that the created ImagePyramid may contain fewer levels as the coarsest level is limited to a side of max 16 pixels. |
| Name | Type | Description |
|---|---|---|
pyramidImage |
OBJECT Image.Pyramid |
Reference to the resized pyramid, or nil if something goes wrong. Note that the function works inplace, modifying the object directly, the output is mainly for error checking. |
pyramidImage = Image.Pyramid.resize(pyramidImage, levelCount)
setProcessingUnit()
Set processing unit to use for pyramid generation.
| Name | Type | Description |
|---|---|---|
pyramidImage |
OBJECT Image.Pyramid |
The image pyramid. |
processingUnit |
ENUM ProcessingUnit |
Processing Unit to use (CPU, FPGA). |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if set was successful. |
success = Image.Pyramid.setProcessingUnit(pyramidImage, "CPU")
toString()
Get a brief string description of the image pyramid. This is equal to the text shown in the debugger to describe the image pyramid.
| Name | Type | Description |
|---|---|---|
pyramidImage |
CONST_OBJECT Image.Pyramid |
The image pyramid. |
| Name | Type | Description |
|---|---|---|
string |
STRING |
Description of the image pyramid |
print("Description: " .. Image.Pyramid.toString(pyramidImage))
Image.ShapeFitter
This is a tool for fitting geometrical object like lines, circles and ellipses to edges and contours in an image. For grayscale images, the geometrical objects are fitted to transitions between dark and bright image contents. For heightmaps, they are fitted to transitions between low and high z values. To get started, create a ShapeFitter with the create function and then call fitLine, fitCircle or fitEllipse to adjust a line, circle or ellipse to fit to the image data. These are primarily intended for intensity images, however images with missing data are supported. For height maps, the function fitLine3D fits a 3D line to edges in the height map. For more detailed control of the fitting behavior, call the set functions before calling the fit function. The shape fitting procedure consists of the following steps: - A number of probe lines are created along the search region. An edge point is found on each probe line. - The geometrical object that best fits to the detected edge points is returned.
Keywords
RANSAC, contour, edges, least squares, model, fitting
See also
Overview
Functions
create()
Create a shape fitter with default settings.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Created shape fitter. |
shapeFitter = Image.ShapeFitter.create()
fitArc()
Fit a circular arc using the current settings within a search region defined by a shape sector. The angular extent of the fitted arc is copied from the search sector. Image world coordinate system handling: The arc is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the arc is only fitted to valid data.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
image |
CONST_OBJECT Image |
Input image. |
searchSector |
CONST_OBJECT Shape |
Search region, defining the search region center, inner and outer radii, and the angles that limit the sector. |
| Name | Type | Description |
|---|---|---|
arc |
OBJECT Shape |
Fitted arc. |
quality |
FLOAT |
Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final circle and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%. |
arc, quality = Image.ShapeFitter.fitArc(shapeFitter, image, searchSector)
fitCircle()
Fit a circle using the current settings within a search region defined by two concentric circles. Image world coordinate system handling: The circle is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the circle is only fitted to valid data.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
image |
CONST_OBJECT Image |
Input image. |
outerCircle |
CONST_OBJECT Shape |
Outer circle of the search region, defining the search region center and outer radius of the search region. |
innerRadius |
FLOAT |
Inner radius of the search region. |
| Name | Type | Description |
|---|---|---|
circle |
OBJECT Shape |
Fitted circle. |
quality |
FLOAT |
Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final circle and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%. |
circle, quality = Image.ShapeFitter.fitCircle(shapeFitter, image, outerCircle, innerRadius)
fitCircle3D()
Fit a circle in 3D using the current settings. In addition to the xy-region defined by the outerCircle and the innerRadius, the zBounds parameter allows limiting the edge point search space in height. Image world coordinate system handling: The circle is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the circle is only fitted to valid data.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
image |
CONST_OBJECT Image |
Input image. |
outerCircle |
CONST_OBJECT Shape |
Outer circle of the search region, defining the search region center and outer radius of the search region. |
innerRadius |
FLOAT |
Inner radius of the search region. |
zBounds |
FLOAT |
Two values providing the min and max z values where edges are searched for. |
| Name | Type | Description |
|---|---|---|
circle |
OBJECT Shape3D |
Fitted circle. |
quality |
FLOAT |
Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final line and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%. |
circle, quality = Image.ShapeFitter.fitCircle3D(shapeFitter, image, outerCircle, innerRadius, zBounds
fitEllipse()
Fit an ellipse using the current settings within a search region defined by two concentric circles. For ellipse fitting, least squares methods are very sensitive to noise. Using the ransac method is highly recommended. Image world coordinate system handling: The ellipse is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the ellipse is only fitted to valid data.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
image |
CONST_OBJECT Image |
Input image. |
outerCircle |
CONST_OBJECT Shape |
Outer circle of the search region, defining the search region center and outer radius of the search region. |
innerRadius |
FLOAT |
Inner radius of the search region. |
| Name | Type | Description |
|---|---|---|
ellipse |
OBJECT Shape |
Fitted ellipse, or nil on failure. |
quality |
FLOAT |
Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final ellipse and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%. |
ellipse, quality = Image.ShapeFitter.fitEllipse(shapeFitter, image, outerCircle, innerRadius)
fitLine()
Fit a line using the current settings. The direction parameter specifies the direction of the probe lines, and should be an angle in radians pointing across the edge. - If direction = 0, the probes are oriented left-to-right (expecting to cross the edge when moving left-to-right in the image). - If direction = PI/2, the probes are oriented top-to-bottom (expecting to cross the edge when moving top-to-bottom in the image). Image world coordinate system handling: The line is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the line is only fitted to valid data.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
image |
CONST_OBJECT Image |
Input image. |
region |
CONST_OBJECT Image.PixelRegion |
Input region. |
direction |
FLOAT |
Approximate edge direction in radians, defines the direction of the edge probes. |
| Name | Type | Description |
|---|---|---|
lineSeg |
OBJECT Shape |
Fitted line segment or nil on failure. |
quality |
FLOAT |
Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final line and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%. |
lineSeg, quality = Image.ShapeFitter.fitLine(shapeFitter, image, region, direction)
fitLine3D()
Fit a 3D line using the current settings. In addition to the xy-region defined by the PixelRegion parameter, the zBounds parameter allows limiting the edge point search space in height. The direction parameter specifies the direction of the probe lines, and should be an angle in radians pointing across the edge. - If direction = 0, the probes are oriented left-to-right (expecting to cross the edge when moving left-to-right in the image). - If direction = PI/2, the probes are oriented top-to-bottom (expecting to cross the edge when moving top-to-bottom in the image). Image world coordinate system handling: The line is fitted in world coordinates. Missing data handling: Pixels with missing data are ignored, the line is only fitted to valid data.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
image |
CONST_OBJECT Image |
Input image. |
region |
CONST_OBJECT Image.PixelRegion |
Input region, defines an area in xy-space. |
zBounds |
FLOAT |
Two values providing the min and max z values where edges are searched for. |
direction |
FLOAT |
Approximate edge direction in radians, defines the direction of the edge probes. |
| Name | Type | Description |
|---|---|---|
lineSegment |
OBJECT Shape3D |
The fitted line segment or nil on failure. |
quality |
FLOAT |
Vector with fitting quality measurements [meanError, inlierRate, edgePointRate], where meanError is the average fitting error of inlier points in world coordinates, inlierRate is the rate of input points that were used to fit the final line and edgePointRate is the rate of edge probes where an edge point was found. For the least squares method, all points are used and the inlier rate is always 100%. |
lineSegment, quality = Image.ShapeFitter.fitLine3D(shapeFitter, image, region, zBounds, direction)
getEdgePoints()
Get the edge points used in the last call to any of the 2D fit functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final shape. The second list contains all points that were extracted but not used for fitting the shape. For the least squares method, all points are always in the first list. Image world coordinate system handling: The points are returned in world coordinates. Missing data handling: Pixels with missing data are ignored, the edge points are only located on valid data.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
| Name | Type | Description |
|---|---|---|
inlierPoints |
OBJECT Point |
Points used for the final fitting of the shape, a subset of the detected points. |
outlierPoints |
OBJECT Point |
Points not used for the final fitting, the remainder of the detected points. |
inlierPoints, outlierPoints = Image.ShapeFitter.getEdgePoints(shapeFitter)
getEdgePoints3D()
Get the 3D edge points used in the last call to any of the 3D fit functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final shape. The second list contains all points that were extracted but not used for fitting the shape. For the least squares method, all points are always in the first list. Image world coordinate system handling: The points are returned in world coordinates. Missing data handling: Pixels with missing data are ignored, the edge points are only located on valid data.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
| Name | Type | Description |
|---|---|---|
inlierPoints |
OBJECT Point |
Points used for the final fitting of the shape, a subset of the detected points. |
outlierPoints |
OBJECT Point |
Points not used for the final fitting, the remainder of the detected points. |
points = Image.ShapeFitter.getEdgePoints3D(shapeFitter)
setDifferenceStep()
Controls the distance between the two points from which the edge height / strength is measured. Increasing this value can improve the accuracy for very blurred edges, where there is no sharp transition from dark to bright (or from low to high z value for height maps).
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
step |
INT |
Difference step in pixels, must be greater than or equal to 1. The default values is 2. |
Image.ShapeFitter.setDifferenceStep(shapeFitter, 5)
setFitMode()
Set the geometrical fitting mode. The following modes are supported: - LEASTSQUARES uses all points. This is fast and easy, but can produce poor results if there are many spurious edge points nearby (default). When using this method, the inlier rate will always be 100%. - RANSAC is a robust method with outlier rejection. Using this method, spurious edge points can be ignored. This mode requires an outlier margin to be set by setOutlierMargin. The number of iterations can be set by setIterations. - TRIMMED is a two-stage least squares method, where points further away from the fitted shape in the first round than the outlier margin (set by setOutlierMargin) is removed before using least squares again to fit a new shape to the remaining points. This is faster than RANSAC but not as robust to outliers.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
fitMode |
ENUM Shape.PointFitMode |
Geometrical fitting mode to use. The default is LEASTSQUARES. For many applications this should be changed to RANSAC to be robust to outliers. |
Image.ShapeFitter.setFitMode(shapeFitter, "RANSAC")
setInterpolation()
Set which interpolation method to use in the edge profiles. The default value, NEAREST, is often a good choice. Changing to LINEAR can give slightly better accuracy, but with additional computational cost.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
interpolation |
ENUM InterpolationMethod |
Interpolation method. |
Image.ShapeFitter.setInterpolation(shapeFitter, "LINEAR")
setIterations()
Set the number of iterations in the point fitting step. Only used when setFitMode specifies a robust method like RANSAC. A higher value makes the method more robust, but consumes more computation time. The default is 100 iterations.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
iterations |
INT |
Number of iterations. |
Image.ShapeFitter.setIterations(shapeFitter, 50)
setOutlierMargin()
Set the outlier margin in world units for the final geometrical fitting step. This parameter is not used for the default fitting method, least squares. The interpretation of the parameter depends on the fitting mode parameter: - ABSOLUTE: the outlier margin is defined in absolute world units (typically mm). Any points further away from the fitted geometrical object than this margin will be ignored. - RANK: the outlier margin is interpreted as a rank measure, defining the rate of points to include. In this case, the margin must be in the range (0.0, 1.0). A rank margin of 0.7 means that only the best fitting 70% of all points will be included, and the rest ignored. In general a larger value means that more points are included in the fitting, which can improve the accuracy as long as all included points are valid. A smaller value makes the algorithm reject more points, which can increases robustness against single erroneous points. The default is an ABSOLUTE margin of 1.0 world units. Image world coordinate system handling: The ABSOLUTE margin is expressed in world coordinate units.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
margin |
FLOAT |
Outlier margin, expressed in world coordinate units or as a rank measure, depending on the marginType. |
marginType |
Outlier margin type. Default is ABSOLUTE. |
Image.ShapeFitter.setOutlierMargin(shapeFitter, margin, marginType)
setPolarity()
Set the edge polarity that the shape fitter is looking for. This controls the kind of transition that the fitter will look for: - POSITIVE means dark-to-bright for grayscale images, and low-to-high for heightmaps. - NEGATIVE means bright-to-dark for grayscale images and high-to-low for heightmaps. - ANY means any of the above (default). This is related to the probe direction, which for line fitting is a parameter to fitLine. For circle and ellipse fitting, the probe direction is always from the center and out.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
polarity |
Edge polarity. |
Image.ShapeFitter.setPolarity(shapeFitter, "POSITIVE")
setProbeCount()
Set the edge probe count. A lower number reduces computation time but also reduces accuracy. If a very large number if specified, the number of probes is limited such that the spacing between probes is at most one pixel. Default: 100 probes.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
count |
INT |
Probe count. Must be >= 4. |
Image.ShapeFitter.setProbeCount(shapeFitter, count)
setSelection()
Decide which edge point to select if there are several candidates available. The selection is related to the probe direction, which for line fitting is a parameter to fitLine. For circle and ellipse fitting, the probe direction is always from the center and out. If using FIRST or LAST, remember to set the edge threshold. - STRONGEST selects the strongest edge along the probe (default). - FIRST selects the first edge encountered along the probe. - LAST selects the last edge encountered along the probe.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
selection |
ENUM EdgeSelection |
Edge selection criteria. |
Image.ShapeFitter.setSelection(shapeFitter, "FIRST")
setSide()
Decide which side of the edge to adjust to. This will adjust the edge points slightly towards the high or low side of the edge, or keep the edge at the center. - CENTER centers the point on the edge (default for intensity images). - HIGH selects the point on the high/bright side of the edge (default for height maps). - LOW selects the point on the low/dark side of the edge.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
side |
ENUM Profile.EdgeSide |
Edge side. |
Image.ShapeFitter.setSide(shapeFitter, "HIGH")
setThreshold()
Set the edge threshold. For grayscale images, this can be interpreted as the required edge sharpness. For height maps, this can be interpreted as the edge step. A higher value means that only strong transitions are considered. The default value is 0, which only works well together with STRONGEST as edge selection criterion (see setSelection). If the selection criteria is FIRST or LAST, a threshold should be specified using this function. Image world coordinate system handling: The threshold is expressed in world coordinates, taking the pixel z-size into account.
| Name | Type | Description |
|---|---|---|
shapeFitter |
HANDLE |
Shape fitter to use. |
threshold |
FLOAT |
Threshold value. The default value is 0, which only works well together with STRONGEST as edge selection critetion in the setSelection function. Increase threshold for other setting of setSelection. |
Image.ShapeFitter.setThreshold(shapeFitter, 10)
Image.SurfaceFitter
This is a tool for fitting geometrical 3D object like planes and rectangles to surfaces in range images. To get started, create a SurfaceFitter with the create function and then call fitPlane or fitRectangle to adjust a plane or rectangle to image data. For more detailed control of the fitting behavior, call the set functions before calling the fit function. The surface fitting procedure consists of the following steps: - The set of points corresponding to the pixels within the PixelRegion and z-value bounds is found. A 3D shape enclosing the desired part of the height map can be converted to a PixelRegion and z-bounds via Shape3D.toPixelRegion(). - The geometrical object that best fits the detected points is returned.
Keywords
RANSAC, least squares, model, fitting
Overview
Functions
create()
Create a surface fitter with default settings.
| Name | Type | Description |
|---|---|---|
surfaceFitter |
HANDLE |
Created surface fitter. |
surfaceFitter = Image.SurfaceFitter.create()
fitPlane()
Fit a 3D plane to image height values within a specified region using the current fit mode. The distance along the z-direction from the height map entries to the plane is minimized. Image world coordinate system handling: The plane is fitted in world coordinates. Missing data handling: Pixels with missing data are disregarded, the plane is only fitted to valid data.
| Name | Type | Description |
|---|---|---|
surfaceFitter |
HANDLE |
Surface fitter to use. |
image |
CONST_OBJECT Image |
Input image. |
region |
CONST_OBJECT Image.PixelRegion |
Input region indicating which area to fit to. Optional, the default is to use the entire image. |
boundsZ |
FLOAT |
Lower and upper z-bound. Optional, the default is to use all points. |
| Name | Type | Description |
|---|---|---|
plane |
OBJECT Shape3D |
The fitted plane. |
quality |
FLOAT |
Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the plane. |
plane, quality = Image.SurfaceFitter.fitPlane(surfaceFitter, image, region, lowerBoundZ, upperBoundZ)
fitRectangle()
Fit a rectangle in 3D to image height values within a specified region using the current fit mode. Similar to fitPlane but the rectangle is limited to the extent of the fitted points. By default, the rectangle is rotated in-plane to find the minimal area rectangle enclosing the inlier points. The distance along the z-direction from the height map entries to the plane is minimized. Image world coordinate system handling: The rectangle is fitted in world coordinates. Missing data handling: Pixels with missing data are disregarded, the rectangle is only fitted to valid data.
| Name | Type | Description |
|---|---|---|
surfaceFitter |
HANDLE |
Surface fitter to use. |
image |
CONST_OBJECT Image |
Input image. |
region |
CONST_OBJECT Image.PixelRegion |
Input region indicating which area to fit to. Optional, the default is to use the entire image. |
boundsZ |
FLOAT |
Lower and upper z-bound. Optional, the default is to use all points. |
oriented |
BOOL |
Flag controlling if the rectangle should be rotated to minimize rectangle area (default). If set to false, the in-plane rotation of the fitted rectangle is related to the coordinate axes. |
| Name | Type | Description |
|---|---|---|
rectangle |
OBJECT Shape3D |
The fitted rectangle. |
quality |
FLOAT |
Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the rectangle. |
rectangle, quality = Image.SurfaceFitter.fitRectangle(surfaceFitter, image, region, zBounds, oriented)
getSurfacePoints()
Get the 3D points used in the last call to any of the fit functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final shape. The second list contains all points that were extracted but not used for fitting the shape. For the least squares method, all points are always in the first list. The number of returned points is limited. If the total number of points exceeds the set limit, the last points are skipped. Image world coordinate system handling: The returned points are in world coordinates. Missing data handling: Pixels with missing data are disregarded.
| Name | Type | Description |
|---|---|---|
surfaceFitter |
HANDLE |
Surface fitter to use. |
pointCountLimit |
INT |
Limit the number of points returned. Optional, default is 50000 points maximum. |
| Name | Type | Description |
|---|---|---|
inlierPoints |
OBJECT Point |
Points used for the final fitting of the shape, a subset of the detected points. |
outlierPoints |
OBJECT Point |
Points not used for the final fitting, the remainder of the detected points. |
inlierPoints, outlierPoints = Image.SurfaceFitter.getSurfacePoints(surfaceFitter)
setFitMode()
Set the geometrical fitting mode. The following modes are supported: - LEASTSQUARES includes all points. This is fast and easy, but can produce poor results if there are many spurious points nearby (default). - RANSAC is a robust method with outlier rejection. Using this method, spurious points can be ignored. This mode requires an outlier margin to be set by setOutlierMargin and uses the number of iterations set through setIterations. - TRIMMED is faster than ransac and more robust than least squares. It first fits a plane to all points using least squares. The points farther from the plane than set outlierMargin are removed and a new plane is fitted to the remaining points using least squares.
| Name | Type | Description |
|---|---|---|
surfaceFitter |
HANDLE |
Surface fitter to use. |
fitMode |
ENUM Shape.PointFitMode |
Geometrical fitting mode to use. The default is LEASTSQUARES. For many applications this should be changed to RANSAC to be robust to outliers. |
Image.SurfaceFitter.setFitMode(surfaceFitter, fitMode)
setIterations()
Set the number of iterations in the point fitting step. Only used when setFitMode specifies a robust method like RANSAC. A higher value makes the method more robust, but consumes more computation time.
| Name | Type | Description |
|---|---|---|
surfaceFitter |
HANDLE |
Surface fitter to use. |
iterations |
INT |
Number of iterations. The default is 100 iterations. |
Image.SurfaceFitter.setIterations(surfaceFitter, iterations)
setOutlierMargin()
Set the outlier margin for the final geometrical fitting step. The interpretation of the margin value depends on the margin type. For an ABSOLUTE margin, any points further away from the fitted geometrical object than this margin will be ignored. The RANK margin includes a given part of the point set, i.e. a rank margin of 0.7 will search for the best shape fitting 70% of the points. For both margin types, a large value means that more points are included in the fitting, which can improve the accuracy as long as all included points are valid. A smaller value makes the algorithm reject more points, which can increases robustness against single erroneous points. The default value is 1.0 world units. Image world coordinate system handling: The ABSOLUTE margin is in image world coordinates.
| Name | Type | Description |
|---|---|---|
surfaceFitter |
HANDLE |
Surface fitter to use. |
margin |
FLOAT |
Outlier margin, expressed in world coordinate unit or as a rank measure, depending on the marginType. |
marginType |
Outlier margin type. Default is ABSOLUTE. |
Image.SurfaceFitter.setOutlierMargin(surfaceFitter, margin, marginType)
setReductionFactor()
Allows for quick reduction of the number of points to fit a shape to for large surfaces. Every N:th pixel in every N:th row is used, reducing computation time. Setting this parameter to one (default) fits the shape to all pixels in the region. Setting this parameter to two, approximately one quarter of the pixels are used.
| Name | Type | Description |
|---|---|---|
surfaceFitter |
HANDLE |
Surface fitter to use. |
n |
INT |
Using every n:th pixel in every n:th row. |
Image.SurfaceFitter.setReductionFactor(surfaceFitter, n)
LED
Access to the LEDs of the device to change their mode. Can be used to activate or deactivate LEDs. If LED support for colors might be possible, there is the function setColor which can be used to change the LED color.
Overview
Functions
activate()
Sets the LED to active. Some LEDs might deactivate theirself after a max. possible active time (e.g. 10 secs). This depends on the concrete LED.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the LED |
activeTimeMs |
INT |
The time the LED is active. Per default stays active forever or might be deactivated after the max. possible active time of the LED (see concrete LED documentation) |
LED.activate(handle)
blink()
Sets the LED to blinking mode so that it is automatically set to active and inactive for the specified times.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle of the LED |
pulsTimeMs |
INT |
The time the LED is active |
pauseTimeMs |
INT |
The time the LED is inactive. If not specified, the pulseTimeMs is also used as pauseTimeMs. |
LED.blink(handle, 600, 300)
create()
Creates a handle for the LED if exists and not already in use.
| Name | Type | Description |
|---|---|---|
ledName |
ENUM LEDs |
The name of the LED to use |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle for the LED. Nil if not available or already in use. |
handle = LED.create("LED_1")
deactivate()
Sets the LED to inactive.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle to the LED |
LED.deactivate(handle)
setColor()
If the LED supports multiple colors it could be set here. If LED is already activated, the color is switched directly. Default is set all to full color (white or the only color the LED supports). The possible colors of the LED could be get known from the device manual.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle of the LED |
color |
AUTO |
Flexible parameter to set the color. Could be a name of a color, a single int RGB value (e.g. 0x123456) or a vector of three ints for each part of the RGB value. |
by name: LED.setColor(handle, "red")
by RGB value: LED.setColor(handle, {255,0,0} )
by RGB state: LED.setColor(handle, {true,false,false} )
LUA.debug
This library provides the functionality of the debug interface (4.9) to Lua programs. You should exert care when using this library. Several of its functions violate basic assumptions about Lua code (e.g., that variables local to a function cannot be accessed from outside; that userdata metatables cannot be changed by Lua code; that Lua programs do not crash) and therefore can compromise otherwise secure code. Moreover, some functions in this library may be slow. All functions in this library are provided inside the debug table. All functions that operate over a thread have an optional first argument which is the thread to operate over. The default is always the current thread.
Overview
Functions
getinfo()
Returns a table with information about a function. You can give the function directly or you can give a number as the value of f, which means the function running at level f of the call stack of the given thread: level 0 is the current function (getinfo itself); level 1 is the function that called getinfo (except for tail calls, which do not count on the stack); and so on. If f is a number larger than the number of active functions, then getinfo returns nil. The returned table can contain all the fields returned by lua_getinfo, with the string what describing which fields to fill in. The default for what is to get all information available, except the table of valid lines. If present, the option 'f' adds a field named func with the function itself. If present, the option 'L' adds a field named activelines with the table of valid lines. For instance, the expression debug.getinfo(1,"n").name returns a name for the current function, if a reasonable name can be found, and the expression debug.getinfo(print) returns a table with all available information about the print function.
| Name | Type | Description |
|---|---|---|
thread |
AUTO |
thread |
f |
AUTO |
|
what |
STRING |
| Name | Type | Description |
|---|---|---|
table |
AUTO |
table |
getlocal()
This function returns the name and the value of the local variable with index local of the function at level f of the stack. This function accesses not only explicit local variables, but also parameters, temporaries, etc. The first parameter or local variable has index 1, and so on, following the order that they are declared in the code, counting only the variables that are active in the current scope of the function. Negative indices refer to vararg parameters; -1 is the first vararg parameter. The function returns nil if there is no variable with the given index, and raises an error when called with a level out of range. (You can call debug.getinfo to check whether the level is valid.) Variable names starting with '(' (open parenthesis) represent variables with no known names (internal variables such as loop control variables, and variables from chunks saved without debug information). The parameter f may also be a function. In that case, getlocal returns only the name of function parameters.
| Name | Type | Description |
|---|---|---|
thread |
AUTO |
thread |
f |
AUTO |
|
local |
INT |
| Name | Type | Description |
|---|---|---|
name |
STRING |
|
value |
AUTO |
getmetatable()
Returns the metatable of the given value or nil if it does not have a metatable.
| Name | Type | Description |
|---|---|---|
value |
AUTO |
| Name | Type | Description |
|---|---|---|
table |
AUTO |
table |
getregistry()
Returns the registry table (see lua reference 4.5).
| Name | Type | Description |
|---|---|---|
table |
AUTO |
table |
traceback()
If message is present but is neither a string nor nil, this function returns message without further processing. Otherwise, it returns a string with a traceback of the call stack. The optional message string is appended at the beginning of the traceback. An optional level number tells at which level to start the traceback (default is 1, the function calling traceback).
| Name | Type | Description |
|---|---|---|
thread |
AUTO |
thread |
message |
STRING |
|
level |
INT |
| Name | Type | Description |
|---|---|---|
message |
STRING |
LUA.math
This library provides basic mathematical functions. It provides all its functions and constants inside the table math. Functions with the annotation "integer/float" give integer results for integer arguments and float results for float (or mixed) arguments. Rounding functions (math.ceil, math.floor, and math.modf) return an integer when the result fits in the range of an integer, or a float otherwise.
Overview
Functions
abs()
Returns the absolute value of x. (integer/float)
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
abs |
FLOAT |
number |
acos()
Returns the arc cosine of x (in radians).
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
acos |
FLOAT |
number |
asin()
Returns the arc sine of x (in radians).
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
asin |
FLOAT |
number |
atan()
Returns the arc tangent of y/x (in radians), but uses the signs of both parameters to find the quadrant of the result. (It also handles correctly the case of x being zero.) The default value for x is 1, so that the call math.atan(y) returns the arc tangent of y.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
atan |
FLOAT |
number |
atan2()
DEPRECATED: Use "atan" instead with additional argument. Returns the arc tangent of y/x (in radians), but uses the signs of both parameters to find the quadrant of the result. (It also handles correctly the case of x being zero.)
| Name | Type | Description |
|---|---|---|
y |
FLOAT |
number |
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
atan2 |
FLOAT |
number |
ceil()
Returns the smallest integral value larger than or equal to x.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
ceil |
FLOAT |
number |
cos()
Returns the cosine of x (assumed to be in radians).
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
cos |
FLOAT |
number |
cosh()
DEPRECATED: Use an external library or implement it in Lua. Returns the hyperbolic cosine of x.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
cosh |
FLOAT |
number |
deg()
Returns the angle x (given in radians) in degrees.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
deg |
FLOAT |
number |
exp()
Returns the value e^x (where e is the base of natural logarithms).
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
exp |
FLOAT |
number |
floor()
Returns the largest integral value smaller than or equal to x.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
floor |
FLOAT |
number |
fmod()
Returns the remainder of the division of x by y that rounds the quotient towards zero. (integer/float)
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
y |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
fmod |
FLOAT |
number |
frexp()
DEPRECATED: Use an external library or implement it in Lua. Returns m and e such that x = m2^e, e is an integer and the absolute value of m is in the range [0.5, 1) (or zero when x is zero).
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
m |
FLOAT |
number |
e |
FLOAT |
number |
ldexp()
DEPRECATED: Replace with "x*2.0^e". Returns m2^e (e should be an integer).
| Name | Type | Description |
|---|---|---|
m |
FLOAT |
number |
e |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
ldexp |
FLOAT |
number |
log()
Returns the logarithm of x in the given base. The default for base is e (so that the function returns the natural logarithm of x).
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
base |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
log |
FLOAT |
number |
log10()
DEPRECATED: Use "log" instead with additional argument. Returns the logarithm of x in base 10.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
log10 |
FLOAT |
number |
max()
Returns the argument with the maximum value, according to the Lua operator < (integer/float)
| Name | Type | Description |
|---|---|---|
x1 |
FLOAT |
number |
x2 |
FLOAT |
number |
xN |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
max |
FLOAT |
number |
min()
Returns the argument with the minimum value, according to the Lua operator >. (integer/float)
| Name | Type | Description |
|---|---|---|
x1 |
FLOAT |
number |
x2 |
FLOAT |
number |
xN |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
min |
FLOAT |
number |
modf()
Returns the integral part of x and the fractional part of x. Its second result is always a float.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
integral |
FLOAT |
number |
fractional |
FLOAT |
number |
pow()
DEPRECATED: Replace with "x^y". Returns x^y. (You can also use the expression x^y to compute this value.)
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
y |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
pow |
FLOAT |
number |
rad()
Returns the angle x (given in degrees) in radians.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
rad |
FLOAT |
number |
random()
When called without arguments, returns a pseudo-random float with uniform distribution in the range [0,1). When called with two integers m and n, math.random returns a pseudo-random integer with uniform distribution in the range [m, n]. (The value n-m cannot be negative and must fit in a Lua integer.) The call math.random(n) is equivalent to math.random(1,n). This function is an interface to the underling pseudo-random generator function provided by C.
| Name | Type | Description |
|---|---|---|
m |
FLOAT |
number |
n |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
random |
FLOAT |
number |
randomseed()
Sets x as the "seed" for the pseudo-random generator: equal seeds produce equal sequences of numbers.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
sin()
Returns the sine of x (assumed to be in radians).
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
sin |
FLOAT |
number |
sinh()
DEPRECATED: Use an external library or implement it in Lua. Returns the hyperbolic sine of x.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
sinh |
FLOAT |
number |
sqrt()
Returns the square root of x. (You can also use the expression x^0.5 to compute this value.)
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
sqrt |
FLOAT |
number |
tan()
Returns the tangent of x (assumed to be in radians).
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
tan |
FLOAT |
number |
tanh()
DEPRECATED: Use an external library or implement it in Lua. Returns the hyperbolic tangent of x.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
tanh |
FLOAT |
number |
tointeger()
If the value x is convertible to an integer, returns that integer. Otherwise, returns nil.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
integer |
INT |
type()
Returns "integer" if x is an integer, "float" if it is a float, or nil if x is not a number.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
number |
| Name | Type | Description |
|---|---|---|
type |
STRING |
ult()
Returns a boolean, true if integer m is below integer n when they are compared as unsigned integers.
| Name | Type | Description |
|---|---|---|
m |
INT |
|
n |
INT |
| Name | Type | Description |
|---|---|---|
ult |
BOOL |
LUA.string
This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. When indexing a string in Lua, the first character is at position 1 (not at 0, as in C). Indices are allowed to be negative and are interpreted as indexing backwards, from the end of the string. Thus, the last character is at position -1, and so on. The string library provides all its functions inside the table string. It also sets a metatable for strings where the __index field points to the string table. Therefore, you can use the string functions in object-oriented style. For instance, string.byte(s,i) can be written as s:byte(i). The string library assumes one-byte character encodings. 6.4.1 - Patterns Patterns in Lua are described by regular strings, which are interpreted as patterns by the pattern-matching functions string.find, string.gmatch, string.gsub, and string.match. This section describes the syntax and the meaning (that is, what they match) of these strings. Character Class: A character class is used to represent a set of characters. The following combinations are allowed in describing a character class: x: (where x is not one of the magic characters ^$()%.[]-?) represents the character x itself. .: (a dot) represents all characters. %a: represents all letters. %c: represents all control characters. %d: represents all digits. %g: represents all printable characters except space. %l: represents all lowercase letters. %p: represents all punctuation characters. %s: represents all space characters. %u: represents all uppercase letters. %w: represents all alphanumeric characters. %x: represents all hexadecimal digits. %x: (where x is any non-alphanumeric character) represents the character x. This is the standard way to escape the magic characters. Any non-alphanumeric character (including all punctuation characters, even the non-magical) can be preceded by a '%' when used to represent itself in a pattern. [set]: represents the class which is the union of all characters in set. A range of characters can be specified by separating the end characters of the range, in ascending order, with a '-'. All classes %x described above can also be used as components in set. All other characters in set represent themselves. For example, [%w_] (or [_%w]) represents all alphanumeric characters plus the underscore, [0-7] represents the octal digits, and [0-7%l%-] represents the octal digits plus the lowercase letters plus the '-' character. The interaction between ranges and classes is not defined. Therefore, patterns like [%a-z] or [a-%%] have no meaning. [^set]: represents the complement of set, where set is interpreted as above. For all classes represented by single letters (%a, %c, etc.), the corresponding uppercase letter represents the complement of the class. For instance, %S represents all non-space characters. The definitions of letter, space, and other character groups depend on the current locale. In particular, the class [a-z] may not be equivalent to %l. Pattern Item: A pattern item can be a single character class, which matches any single character in the class; a single character class followed by '*', which matches zero or more repetitions of characters in the class. These repetition items will always match the longest possible sequence; a single character class followed by '', which matches one or more repetitions of characters in the class. These repetition items will always match the longest possible sequence; a single character class followed by '-', which also matches zero or more repetitions of characters in the class. Unlike '', these repetition items will always match the shortest possible sequence; a single character class followed by '?', which matches zero or one occurrence of a character in the class. It always matches one occurrence if possible; %n, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below); %bxy, where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item %b() matches expressions with balanced parentheses. %f[set], a frontier pattern; such item matches an empty string at any position such that the next character belongs to set and the previous character does not belong to set. The set set is interpreted as previously described. The beginning and the end of the subject are handled as if they were the character '\0'. Pattern: A pattern is a sequence of pattern items. A caret '^' at the beginning of a pattern anchors the match at the beginning of the subject string. A '$' at the end of a pattern anchors the match at the end of the subject string. At other positions, '^' and '$' have no special meaning and represent themselves. Captures: A pattern can contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored (captured) for future use. Captures are numbered according to their left parentheses. For instance, in the pattern "(a*(.)%w(%s*))", the part of the string matching "a*(.)%w(%s*)" is stored as the first capture (and therefore has number 1); the character matching "." is captured with number 2, and the part matching "%s*" has number 3. As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5. 6.4.2 - Format Strings for Pack and Unpack The first argument to string.pack, string.packsize, and string.unpack is a format string, which describes the layout of the structure being created or read. A format string is a sequence of conversion options. The conversion options are as follows: <: sets little endian >: sets big endian =: sets native endian ![n]: sets maximum alignment to n (default is native alignment) b: a signed byte (char) B: an unsigned byte (char) h: a signed short (native size) H: an unsigned short (native size) l: a signed long (native size) L: an unsigned long (native size) j: a lua_Integer J: a lua_Unsigned T: a size_t (native size) i[n]: a signed int with n bytes (default is native size) I[n]: an unsigned int with n bytes (default is native size) f: a float (native size) d: a double (native size) n: a lua_Number cn: a fixed-sized string with n bytes z: a zero-terminated string s[n]: a string preceded by its length coded as an unsigned integer with n bytes (default is a size_t) x: one byte of padding Xop: an empty item that aligns according to option op (which is otherwise ignored) ' ': (empty space) ignored (A "[n]" means an optional integral numeral.) Except for padding, spaces, and configurations (options "xX <⇒!"), each option corresponds to an argument (in string.pack) or a result (in string.unpack). For options "!n", "sn", "in", and "In", n can be any integer between 1 and 16. All integral options check overflows; string.pack checks whether the given value fits in the given size; string.unpack checks whether the read value fits in a Lua integer. Any format string starts as if prefixed by "!1=", that is, with maximum alignment of 1 (no alignment) and native endianness. Alignment works as follows: For each option, the format gets extra padding until the data starts at an offset that is a multiple of the minimum between the option size and the maximum alignment; this minimum must be a power of 2. Options "c" and "z" are not aligned; option "s" follows the alignment of its starting integer. All padding is filled with zeros by string.pack (and ignored by string.unpack).
Overview
Functions
byte()
Returns the internal numeric codes of the characters s[i], s[i+1], …, s[j]. The default value for i is 1; the default value for j is i. These indices are corrected following the same rules of function string.sub. Numeric codes are not necessarily portable across platforms.
| Name | Type | Description |
|---|---|---|
s |
STRING |
|
i |
INT |
|
j |
INT |
| Name | Type | Description |
|---|---|---|
byte |
INT |
char()
Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numeric code equal to its corresponding argument. Numeric codes are not necessarily portable across platforms.
| Name | Type | Description |
|---|---|---|
x1 |
INT |
|
xN |
INT |
| Name | Type | Description |
|---|---|---|
string |
STRING |
dump()
Returns a string containing a binary representation (a binary chunk) of the given function, so that a later load on this string returns a copy of the function (but with new upvalues). If strip is a true value, the binary representation may not include all debug information about the function, to save space. Functions with upvalues have only their number of upvalues saved. When (re)loaded, those upvalues receive fresh instances containing nil. (You can use the debug library to serialize and reload the upvalues of a function in a way adequate to your needs.)
| Name | Type | Description |
|---|---|---|
function |
AUTO |
function |
| Name | Type | Description |
|---|---|---|
binary |
BINARY |
find()
Looks for the first match of pattern (see 6.4.1) in the string s. If it finds a match, then find returns the indices of s where this occurrence starts and ends; otherwise, it returns nil. A third, optional numeric argument init specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered magic. Note that if plain is given, then init must be given as well. If the pattern has captures, then in a successful match the captured values are also returned, after the two indices.
| Name | Type | Description |
|---|---|---|
s |
STRING |
|
pattern |
STRING |
|
init |
INT |
|
plain |
BOOL |
| Name | Type | Description |
|---|---|---|
x1 |
STRING |
|
xN |
STRING |
format()
Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string). The format string follows the same rules as the ISO C function sprintf. The only differences are that the options/modifiers *, h, L, l, n, and p are not supported and that there is an extra option, q. The q option formats a string between double quotes, using escape sequences when necessary to ensure that it can safely be read back by the Lua interpreter. For instance, the call string.format('%q', 'a string with "quotes" and \n new line') may produce the string: "a string with \"quotes\" and \ new line" Options A, a, E, e, f, G, and g all expect a number as argument. Options c, d, i, o, u, X, and x expect an integer. Option q expects a string. Option s expects a string; if its argument is not a string, it is converted to one following the same rules of tostring. If the option has any modifier (flags, width, length), the string argument should not contain embedded zeros. When Lua is compiled with a non-C99 compiler, options A and a (hexadecimal floats) do not support any modifier (flags, width, length).
| Name | Type | Description |
|---|---|---|
formatstring |
STRING |
|
x1 |
AUTO |
|
xN |
AUTO |
gmatch()
Returns an iterator function that, each time it is called, returns the next captures from pattern (see 6.4.1) over the string s. If pattern specifies no captures, then the whole match is produced in each call. As an example, the following loop will iterate over all the words from string s, printing one per line: s = "hello world from Lua" for w in string.gmatch(s, "%a+") do print(w) end The next example collects all pairs key=value from the given string into a table: t = {} s = "from=world, to=Lua" for k, v in string.gmatch(s, "(%w+)=(%w+)") do t[k] = v end For this function, a caret '^' at the start of a pattern does not work as an anchor, as this would prevent the iteration.
| Name | Type | Description |
|---|---|---|
s |
STRING |
|
pattern |
STRING |
| Name | Type | Description |
|---|---|---|
function |
AUTO |
function |
gsub()
Returns a copy of s in which all (or the first n, if given) occurrences of the pattern (see 6.4.1) have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred. The name gsub comes from Global SUBstitution. If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %d, with d between 1 and 9, stands for the value of the d-th captured substring. The sequence %0 stands for the whole match. The sequence %% stands for a single %. If repl is a table, then the table is queried for every match, using the first capture as the key. If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order. In any case, if the pattern specifies no captures, then it behaves as if the whole pattern was inside a capture. If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string). Here are some examples: x = string.gsub("hello world", "(%w+)", "%1 %1") -→ x="hello hello world world" x = string.gsub("hello world", "%w+", "%0 %0", 1) -→ x="hello hello world" x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") -→ x="world hello Lua from" x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) -→ x="home = /home/roberto, user = roberto" x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) return load(s)() end) -→ x="4+5 = 9" local t = {name="lua", version="5.3"} x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) -→ x="lua-5.3.tar.gz"
| Name | Type | Description |
|---|---|---|
s |
STRING |
|
pattern |
STRING |
|
repl |
AUTO |
|
n |
AUTO |
number |
| Name | Type | Description |
|---|---|---|
copyS |
STRING |
|
numberOfMatches |
INT |
len()
Receives a string and returns its length. The empty string "" has length 0. Embedded zeros are counted, so "a\000bc\000" has length 5.
| Name | Type | Description |
|---|---|---|
s |
STRING |
| Name | Type | Description |
|---|---|---|
len |
INT |
lower()
Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.
| Name | Type | Description |
|---|---|---|
s |
STRING |
| Name | Type | Description |
|---|---|---|
string |
STRING |
match()
Looks for the first match of pattern in the string s. If it finds one, then match returns the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative.
| Name | Type | Description |
|---|---|---|
s |
STRING |
|
pattern |
STRING |
|
init |
INT |
| Name | Type | Description |
|---|---|---|
string |
STRING |
pack()
Returns a binary string containing the values v1, v2, etc. packed (that is, serialized in binary form) according to the format string fmt (see string description).
| Name | Type | Description |
|---|---|---|
fmt |
STRING |
|
v1 |
AUTO |
|
vN |
AUTO |
| Name | Type | Description |
|---|---|---|
binaryString |
STRING |
packsize()
Returns the size of a string resulting from string.pack with the given format. The format string cannot have the variable-length options 's' or 'z' (see 6.4.2).
| Name | Type | Description |
|---|---|---|
fmt |
STRING |
| Name | Type | Description |
|---|---|---|
packsize |
INT |
rep()
Returns a string that is the concatenation of n copies of the string s separated by the string sep. The default value for sep is the empty string (that is, no separator). Returns the empty string if n is not positive. (Note that it is very easy to exhaust the memory of your machine with a single call to this function.)
| Name | Type | Description |
|---|---|---|
s |
STRING |
|
n |
INT |
|
sep |
STRING |
| Name | Type | Description |
|---|---|---|
string |
STRING |
reverse()
Returns a string that is the string s reversed.
| Name | Type | Description |
|---|---|---|
s |
STRING |
| Name | Type | Description |
|---|---|---|
string |
STRING |
sub()
Returns the substring of s that starts at i and continues until j; i and j can be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.sub(s,1,j) returns a prefix of s with length j, and string.sub(s, -i) returns a suffix of s with length i. If, after the translation of negative indices, i is less than 1, it is corrected to 1. If j is greater than the string length, it is corrected to that length. If, after these corrections, i is greater than j, the function returns the empty string.
| Name | Type | Description |
|---|---|---|
s |
STRING |
|
i |
INT |
|
j |
INT |
| Name | Type | Description |
|---|---|---|
substring |
STRING |
unpack()
Returns the values packed in string s (see string.pack) according to the format string fmt (see 6.4.2). An optional pos marks where to start reading in s (default is 1). After the read values, this function also returns the index of the first unread byte in s.
| Name | Type | Description |
|---|---|---|
fmt |
STRING |
|
s |
STRING |
|
pos |
INT |
|
v1 |
AUTO |
|
v2 |
AUTO |
|
vN |
AUTO |
|
firstUnreadByte |
INT |
upper()
Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.
| Name | Type | Description |
|---|---|---|
s |
STRING |
| Name | Type | Description |
|---|---|---|
string |
STRING |
LUA.table
This library provides generic functions for table manipulation. It provides all its functions inside the table table. Remember that, whenever an operation needs the length of a table, the table must be a proper sequence or have a __len metamethod (see 3.4.7). All functions ignore non-numeric keys in the tables given as arguments.
Functions
concat()
Given a list where all elements are strings or numbers, returns the string list[i]..sep..list[i+1] … sep..list[j]. The default value for sep is the empty string, the default for i is 1, and the default for j is ##list. If i is greater than j, returns the empty string.
| Name | Type | Description |
|---|---|---|
list |
AUTO |
table |
sep |
STRING |
|
i |
INT |
|
j |
INT |
| Name | Type | Description |
|---|---|---|
concat |
STRING |
insert()
Inserts element value at position pos in list, shifting up the elements list[pos], list[pos+1], …, list[list]. The default value for pos is list+1, so that a call table.insert(t,x) inserts x at the end of list t.
| Name | Type | Description |
|---|---|---|
list |
AUTO |
table |
pos |
INT |
|
value |
AUTO |
move()
Moves elements from table a1 to table a2. This function performs the equivalent to the following multiple assignment: a2[t],… = a1[f],…,a1[e]. The default for a2 is a1. The destination range can overlap with the source range. The number of elements to be moved must fit in a Lua integer.
| Name | Type | Description |
|---|---|---|
a1 |
AUTO |
table |
f |
INT |
|
e |
INT |
|
t |
INT |
|
a2 |
AUTO |
table |
pack()
Returns a new table with all parameters stored into keys 1, 2, etc. and with a field "n" with the total number of parameters. Note that the resulting table may not be a sequence.
| Name | Type | Description |
|---|---|---|
x1 |
AUTO |
|
xN |
AUTO |
| Name | Type | Description |
|---|---|---|
table |
AUTO |
table |
remove()
Removes from list the element at position pos, returning the value of the removed element. When pos is an integer between 1 and list, it shifts down the elements list[pos+1], list[pos+2], …, list[list] and erases element list[list]; The index pos can also be 0 when list is 0, or list + 1; in those cases, the function erases the element list[pos]. The default value for pos is list, so that a call table.remove(l) removes the last element of list l.
| Name | Type | Description |
|---|---|---|
list |
AUTO |
table |
pos |
INT |
sort()
Sorts list elements in a given order, in-place, from list[1] to list[##list]. If comp is given, then it must be a function that receives two list elements and returns true when the first element must come before the second in the final order (so that, after the sort, i < j implies not comp(list[j],list[i])). If comp is not given, then the standard Lua operator > is used instead. Note that the comp function must define a strict partial order over the elements in the list; that is, it must be asymmetric and transitive. Otherwise, no valid sort may be possible. The sort algorithm is not stable; that is, elements not comparable by the given order (e.g., equal elements) may have their relative positions changed by the sort.
| Name | Type | Description |
|---|---|---|
list |
AUTO |
table |
comp |
AUTO |
function |
unpack()
Returns the elements from the given list. This function is equivalent to return list[i], list[i+1], …, list[j] By default, i is 1 and j is ##list.
| Name | Type | Description |
|---|---|---|
list |
AUTO |
table |
| Name | Type | Description |
|---|---|---|
x1 |
AUTO |
|
xN |
AUTO |
LUA.utf8
This library provides basic support for UTF-8 encoding. It provides all its functions inside the table utf8. This library does not provide any support for Unicode other than the handling of the encoding. Any operation that needs the meaning of a character, such as character classification, is outside its scope. Unless stated otherwise, all functions that expect a byte position as a parameter assume that the given position is either the start of a byte sequence or one plus the length of the subject string. As in the string library, negative indices count from the end of the string.
Overview
Functions
char()
Receives zero or more integers, converts each one to its corresponding UTF-8 byte sequence and returns a string with the concatenation of all these sequences.
| Name | Type | Description |
|---|---|---|
x1 |
INT |
|
xN |
INT |
| Name | Type | Description |
|---|---|---|
string |
STRING |
codepoint()
Returns the codepoints (as integers) from all characters in s that start between byte position i and j (both included). The default for i is 1 and for j is i. It raises an error if it meets any invalid byte sequence.
| Name | Type | Description |
|---|---|---|
s |
STRING |
|
i |
INT |
|
j |
INT |
| Name | Type | Description |
|---|---|---|
c |
INT |
codes()
Returns values so that the construction for p, c in utf8.codes(s) do body end will iterate over all characters in string s, with p being the position (in bytes) and c the code point of each character. It raises an error if it meets any invalid byte sequence.
| Name | Type | Description |
|---|---|---|
s |
STRING |
| Name | Type | Description |
|---|---|---|
p |
INT |
|
c |
INT |
len()
Returns the number of UTF-8 characters in string s that start between positions i and j (both inclusive). The default for i is 1 and for j is -1. If it finds any invalid byte sequence, returns a false value plus the position of the first invalid byte.
| Name | Type | Description |
|---|---|---|
s |
STRING |
|
i |
INT |
|
j |
INT |
| Name | Type | Description |
|---|---|---|
len |
INT |
offset()
Returns the position (in bytes) where the encoding of the n-th character of s (counting from position i) starts. A negative n gets characters before position i. The default for i is 1 when n is non-negative and ##s + 1 otherwise, so that utf8.offset(s, -n) gets the offset of the n-th character from the end of the string. If the specified character is neither in the subject nor right after its end, the function returns nil. As a special case, when n is 0 the function returns the start of the encoding of the character that contains the i-th byte of s. This function assumes that s is a valid UTF-8 string.
| Name | Type | Description |
|---|---|---|
s |
STRING |
|
n |
INT |
|
i |
INT |
| Name | Type | Description |
|---|---|---|
offset |
INT |
Log
Provides logging capabilities for Apps.
Overview
Functions
fine()
Logs a message with level "FINE"
| Name | Type | Description |
|---|---|---|
msg |
STRING |
The message to print out |
Log.fine("My message")
finer()
Logs a message with level "FINER"
| Name | Type | Description |
|---|---|---|
msg |
STRING |
The message to print out |
Log.finer("My message")
finest()
Logs a message with level "FINEST"
| Name | Type | Description |
|---|---|---|
msg |
STRING |
The message to print out |
Log.finest("My message")
info()
Logs a message with level "INFO"
| Name | Type | Description |
|---|---|---|
msg |
STRING |
The message to print out |
Log.info("My message")
isLogable()
Returns true if the logging on the specified level is enabled. This is useful to don’t create big log outputs if the logging is disabled and log output would not be used. Only interesting for log levels smaller than warning, because warning and severe output always is needed.
| Name | Type | Description |
|---|---|---|
level |
ENUM Level |
The level |
| Name | Type | Description |
|---|---|---|
isLogable |
BOOL |
True if the logging on the specified level is enabled |
setConsoleMode()
Sets the logging handling to console mode (=default). This overwrites all other modes; only one mode can be assigned to the App’s logger.
Log.setConsoleMode()
setFileMode()
Sets the logging handling to file mode. This overwrites all other modes; only one mode can be assigned to the App’s logger. The writing of the logs to the logfile is done asynchronously in the background. The maximum number of logs in the queue for writing to file is 128 for each app. If the log queue is full, the new log is thrown away. The logfile will contain a "Some log messages were lost"-string if this happened. In this case the rate of log production has to be reduced by the app. When the maximum file size is reached, the file is divided into two halves: The first half(old entries) is discarded, the second half is shifted to the beginning of the file, so new log entries can be appended at the end. Note that it depends on the underlying operating system if the logged file can be accessed while it is written. If you want to open the logged file for reading, set the logger to another file or to another mode first. Accessing files is restricted to the public/ or private/ folder, so you may only use file paths starting with either public/ or private/.
| Name | Type | Description |
|---|---|---|
fileName |
STRING |
File name inside the public or private folder |
maxFileSize |
INT |
Maximum file size in range of 1024 (1 kB) to 104857600 (100 MB) |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
true when setting was successful |
Log.setFileMode("private/log.txt", 1048576)
setLevel()
Sets the logging level for the current App
| Name | Type | Description |
|---|---|---|
level |
ENUM Level |
The level |
Log.setLevel("INFO")
severe()
Logs a message with level "SEVERE"
| Name | Type | Description |
|---|---|---|
msg |
STRING |
The message to print out |
Log.severe("My message")
warning()
Logs a message with level "WARNING"
| Name | Type | Description |
|---|---|---|
msg |
STRING |
The message to print out |
Log.warning("My message")
Log.Handler
Handlers are used to connect one or more loggers to one or more endpoints, the so-called 'sinks'. A sink can be either a file, a callback function or the AppStudio console. Every handler can be attached to an arbitrary number of loggers (local, shared or the engine logger) and an arbitrary number of sinks. However, there is only one global engine logger and only one console sink because AppStudio does not offer multiple consoles. To apply the configuration on a handler, the applyConfig() function must be called. It must also be called after making changes to an already installed handler, e.g. when changing the log level. You can also add callback sinks which use callback functions with the following signature: function myHandlerFunction(message, path, level, timestamp, appName, appPosition, sourceApi) print(message) end The parameters appName, appPosition and sourceApi contain the name of the app, file and line position in the app source code and the name of the API the log was sent from. If this information is not available, the corresponding strings are empty. handler = Log.Handler.create() handler:attachToLogger("App1.myLogger") handler:attachToSharedLogger("mySharedLogger") handler:addFileSink("private/log.txt", 1000000) handler:addCallbackSink("myHandlerFunction") handler:setConsoleSinkEnabled(true) handler:setLevel("WARNING") handler:applyConfig()
Overview
Functions
addCallbackSink()
Adds a callback sink to the handler. The signature is as follows: function myHandlerFunction(message, path, level, timestamp, appName, appPosition, sourceApi) print(message) end The parameters appName, appPosition and sourceApi contain the name of the app, file and line position in the app source code and the name of the API the log was sent from. If this information is not available, the corresponding strings are empty.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
callback |
STRING |
The callback to be triggered when a message is dispatched |
function myHandlerFunction(message, path, level, timestamp, appName, appPosition, sourceApi)
print(message)
end
Log.Handler.addCallbackSink(handle, "myHandlerFunction")
addFileSink()
Adds a file sink to the handler.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
filePath |
STRING |
Path to the log file |
fileSize |
INT |
Maximum size of the log file before truncating. Has to be in the range [1024,104857600]. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if file sink was added, false if an error occurred |
Log.Handler.addFileSink(handle, "private/my.log", 1000000)
applyConfig()
Applies the handle config. This must be called in order to install the low-level handlers with the configuration set on the handle. You must also call it to update the handler after changing settings.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
Log.Handler.applyConfig(handle)
attachToEngineLogger()
Attaches handler to the engine logger.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
Log.Handler.attachToEngineLogger(handle)
attachToLogger()
Attaches handler to an app-local logger.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
appPath |
STRING |
Path of the app logger in the form AppName.LocalLoggerName |
Log.Handler.attachToLogger(handle, "AppName.LoggerName")
attachToSharedLogger()
Attaches handler to a shared logger.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
loggerName |
STRING |
Name of the logger |
Log.Handler.attachToSharedLogger(handle, "LoggerName")
create()
Creates a new Log.Handler instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The new instance |
local handle = Log.Handler.create()
setConsoleSinkEnabled()
Enables/disables forwarding to AppStudio console.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
enabled |
BOOL |
True to enable forwarding to AppStudio console, false to disable |
Log.Handler.setConsoleSinkEnabled(handle, true)
setLevel()
Sets the logging level of the handler.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
level |
ENUM Level |
Log level |
Log.Handler.setLevel(handle, WARNING)
Log.Logger
App-local logger which belongs to the app that creates it. Messages can be logged to the logger by using the functions named after the log levels (info, warning, severe, …). To get output from the logger, a handler must be attached to it and connected to a sink. See Log.Handler for more information. logger = Log.Logger.create("myLogger") logger:warning("This is a warning")
Overview
Functions
create()
Creates a new Log.Logger instance.
| Name | Type | Description |
|---|---|---|
loggerName |
STRING |
Name of the logger |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The new instance |
local handle = Log.Logger.create("loggerName")
fine()
Logs a message with level "FINE"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.Logger.fine(handle, "My message")
finer()
Logs a message with level "FINER"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.Logger.finer(handle, "My message")
finest()
Logs a message with level "FINEST"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.Logger.finest(handle, "My message")
info()
Logs a message with level "INFO"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.Logger.info(handle, "My message")
isLoggable()
Check whether a message with a certain log level will be forwarded with the current level setting or not.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
level |
ENUM Level |
Log level |
| Name | Type | Description |
|---|---|---|
loggable |
BOOL |
True if loggable, false if not |
loggable = Log.Logger.isLoggable(handle, "INFO")
setLevel()
Sets the logging level of the logger.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
level |
ENUM Level |
Log level |
Log.Logger.setLevel(handle, "WARNING")
severe()
Logs a message with level "SEVERE"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.Logger.severe(handle, "My message")
warning()
Logs a message with level "WARNING"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.Logger.warning(handle, "My message")
Log.SharedLogger
Shared logger which can be accessed from any app. The handle created does not 'own' the logger. Messages can be logged to the logger by using the functions named after the log levels (info, warning, severe, …). To get output from the logger, a handler must be attached to it and connected to a sink. See Log.Handler for more information. logger = Log.SharedLogger.create("mySharedLogger") logger:warning("This is a warning")
Overview
Functions
create()
Creates a new Log.SharedLogger instance.
| Name | Type | Description |
|---|---|---|
loggerName |
STRING |
Name of the logger |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The new instance |
local handle = Log.SharedLogger.create("loggerName")
fine()
Logs a message with level "FINE"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.SharedLogger.fine(handle, "My message")
finer()
Logs a message with level "FINER"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.SharedLogger.finer(handle, "My message")
finest()
Logs a message with level "FINEST"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.SharedLogger.finest(handle, "My message")
info()
Logs a message with level "INFO"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.SharedLogger.info(handle, "My message")
isLoggable()
Check whether a message with a certain log level will be forwarded with the current level setting or not.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
level |
ENUM Level |
Log level |
| Name | Type | Description |
|---|---|---|
loggable |
BOOL |
True if loggable, false if not |
loggable = Log.SharedLogger.isLoggable(handle, "INFO")
setLevel()
Sets the logging level of the logger.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
level |
ENUM Level |
Log level |
Log.SharedLogger.setLevel(handle, "WARNING")
severe()
Logs a message with level "SEVERE"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.SharedLogger.severe(handle, "My message")
warning()
Logs a message with level "WARNING"
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
msg |
STRING |
The message to print out |
Log.SharedLogger.warning(handle, "My message")
MachineLearning
Machine learning tools for data understanding and prediction. The Machine Learning API trains classifiers and makes predictions on samples formed by collecting measurements of data as rows in a matrix. Helpers to partition data into training and evaluation set and other convenience functions to manipulate the raw dataset are also included. Classifiers in general support both regression and classification tasks. The selection is made when creating the dataset. Algorithms included - DataSet container for labeled samples. - Classifiers: Neural net, Random Forest, k-Nearest Neighbor, Support Vector Machines, Bayes, Fisher Linear Discriminant - Data dimensionality reduction: Principal Component Analysis (PCA), k-Means clustering - Methods for evaluating classifier accuracy - Methods for data statistics, selection and preconditioning.
Overview
MachineLearning.Bayes
Bayes, or as it is sometimes known, Normal Bayes Classifier, is a really simple classifier. It has no parameters and tries to separate classes by assuming normal distribution within each feature. For data that is approximately Gaussian this classifier works well and is quite quick to evaluate.
Overview
Functions
clear()
Clear internal data of the classifier.
| Name | Type | Description |
|---|---|---|
bayes |
HANDLE |
The classifier instance to use. |
MachineLearning.Bayes.clear(bayes)
create()
Creates a new Bayes classifier.
| Name | Type | Description |
|---|---|---|
bayes |
HANDLE |
The new Bayes handle |
bayes = MachineLearning.Bayes.create()
getAccuracy()
Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.
| Name | Type | Description |
|---|---|---|
bayes |
HANDLE |
The classifier instance to use. |
dataSet |
OBJECT MachineLearning.DataSet |
The dataset to use |
| Name | Type | Description |
|---|---|---|
accuracy |
FLOAT |
The accuracy rate. Computed as correct classifications divided by total amount of samples. |
confusionMatrix |
OBJECT Matrix |
Confusion matrix for dataset and classifier. |
confusionMatrixLabels |
INT |
The label key for the confusion matrix. |
accuracy, confusionMatrix = MachineLearning.Bayes.getAccuracy(bayes, dataSet)
getFeatureCount()
Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.
| Name | Type | Description |
|---|---|---|
bayes |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
featureCount |
INT |
The amount of features per sample. |
trained = MachineLearning.Bayes.getFeatureCount(bayes)
isTrained()
Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.
| Name | Type | Description |
|---|---|---|
bayes |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
trained |
BOOL |
True if the classifier is trained. |
trained = MachineLearning.Bayes.isTrained(bayes)
load()
Load a Bayes classifier from disk.
| Name | Type | Description |
|---|---|---|
path |
STRING |
The path to the classifier |
| Name | Type | Description |
|---|---|---|
bayes |
HANDLE |
The Bayes handle to the loaded object. |
bayes = MachineLearning.Bayes.load(path)
predict()
Classify a sample using the trained classifier.
| Name | Type | Description |
|---|---|---|
bayes |
HANDLE |
The classifier instance to use. |
sample |
OBJECT Matrix |
A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample. |
| Name | Type | Description |
|---|---|---|
class |
FLOAT |
Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels. |
class = MachineLearning.Bayes.predict(bayes, sample)
save()
Save a Bayes classifier to disk.
| Name | Type | Description |
|---|---|---|
bayes |
HANDLE |
The classifier instance to use |
path |
STRING |
The path at which to store the classifier |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if the file was successfully stored, false if storing failed. |
success = MachineLearning.Bayes.save(bayes, path)
toString()
Get a brief string description of the classifier. This is equal to the text shown in the debugger.
| Name | Type | Description |
|---|---|---|
bayes |
OBJECT MachineLearning.Bayes |
The input classifier data |
| Name | Type | Description |
|---|---|---|
string |
STRING |
Description of the classifier |
print("Description: " .. MachineLearning.Bayes.toString(bayes))
train()
Perform training on data supplied in a DataSet object.
| Name | Type | Description |
|---|---|---|
bayes |
HANDLE |
The classifier instance to use |
dataSet |
OBJECT MachineLearning.DataSet |
Input dataset |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if classifier was successfully trained. |
success = MachineLearning.Bayes.train(bayes, dataSet)
MachineLearning.DataSet
Training data container for classical machine learning applications. Stores samples and corresponding labels for input to different classifiers. It is not intended for use together with DeepNeuralNetwork applications. Samples are always floating point values, but labels are integer values for classification tasks and floating point values for regression tasks. It’s possible to also supply weights per sample which some algorithms make use of during training.
Overview
Functions
append()
Append one or multiple samples to the internal list of samples.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
samples |
OBJECT Matrix |
Training sample(s). Each row is considered a separate sample. To add more samples at the same time use a matrix of multiple rows. |
labels |
AUTO |
Training label(s). If all samples belong to the same class send a single label value. Otherwise there should be one sample per row in the samples matrix. |
weight |
OBJECT Matrix |
Optional weights for each sample. This matrix must be single column and have as many rows as samples |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if data was successfully added. |
MachineLearning.DataSet.append(dataSet, sample, label)
calculateNormalization()
Calculate a matrix with the mean and standard deviation for each feature. This matrix is convenient to use as input for normalizing dataset objects as well as raw matrices for example before classification. The matrix consist of the mean and standard deviation for each sample. Means are in the first row, standard deviations in the second.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
| Name | Type | Description |
|---|---|---|
normalization |
OBJECT Matrix |
The normalization matrix. |
normalization = MachineLearning.DataSet.calculateNormalization(dataSet)
calculateProjection()
Calculate a matrix with the means of each feature in the first row and principal component eigen vectors in the following rows. The total height of the returned matrix minus one corresponds to the output dimension after projection.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
maxDimensions |
INT |
Set this value to determine the dimensions of the output. To keep all set to 0 or the original feature size. |
retainVariance |
FLOAT |
Set this to select how much of the original signal to keep. If set to 0.5 it means that at least 50% of the signal energy remains after projection. |
| Name | Type | Description |
|---|---|---|
projection |
OBJECT Matrix |
The projection matrix. |
projection = MachineLearning.DataSet.calculateProjection(dataSet, maxDimensions, retainVariance)
calculateStatistics()
Calculate and return statistics for the dataset object.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
| Name | Type | Description |
|---|---|---|
mean |
FLOAT |
A vector containing the mean for each feature. |
std |
FLOAT |
A vector containing the standard deviation for each feature. |
min |
FLOAT |
A vector containing the minimum value for each feature. |
max |
FLOAT |
A vector containing the maximum value for each feature. |
mean, std, min, max = MachineLearning.DataSet.calculateStatistics(dataSet)
clear()
Remove all internally stored samples. Clearing out samples reduces memory usage and can be useful when large datasets are used for training.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
MachineLearning.DataSet.clear(dataSet)
create()
Creates a new DataSet object
| Name | Type | Description |
|---|---|---|
labelType |
ENUM LabelType |
Create a dataset of the selected type. |
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The new dataset. |
dataSet = MachineLearning.DataSet.create("CLASSIFICATION")
getFeature()
Return a feature from the sample set.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
index |
INT |
The index into the dataset. If left out all all features are returned. This is the same getSample without index. |
| Name | Type | Description |
|---|---|---|
sample |
OBJECT Matrix |
The matrix corresponding to the selected feature index or in case index is left out all features. Each feature is a separate column. |
feature = MachineLearning.DataSet.getFeature(dataSet, index)
getFeatureCount()
Return the number of values stored per sample. This is the same as the number of columns in each sample that has been added.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
| Name | Type | Description |
|---|---|---|
featureCount |
INT |
The amount of features |
featureCount = MachineLearning.DataSet.getFeatureCount(dataSet)
getLabel()
Return label for a sample in the loaded set.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
index |
INT |
The index into the dataset. If left out all labels are returned. |
| Name | Type | Description |
|---|---|---|
label |
AUTO |
The label corresponding to the selected sample index or all labels if no index is supplied. |
label = MachineLearning.DataSet.getLabel(dataSet, index)
getSample()
Return a sample from the sample set.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
index |
INT |
The index into the dataset. If left out all samples are returned. This is the same as getFeature without index. |
| Name | Type | Description |
|---|---|---|
sample |
OBJECT Matrix |
The matrix corresponding to the selected sample index or in case index is left out all samples. Each sample is a separate row. |
sample = MachineLearning.DataSet.getSample(dataSet, index)
getSampleCount()
Return the amount of samples currently stored in the dataset.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
| Name | Type | Description |
|---|---|---|
samplesCount |
INT |
The amount of samples |
samplesCount = MachineLearning.DataSet.getSampleCount(dataSet)
getSubset()
Return a new dataset object of a selected subset of the original dataset.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
start |
INT |
The start index at which to start extracting samples. |
count |
INT |
The amount of samples to extract. If left out all samples after start will be extracted. |
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The new dataset consisting of only selected samples. |
sample = MachineLearning.DataSet.getSubset(dataSet, start, count)
getSubsetInterval()
Return a new dataset object of a selected subset of the original dataset. This function allows extraction of an interval of label values in case the LabelType is REGRESSION.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
minValue |
FLOAT |
The smallest value of a label to keep in the output. |
maxValue |
FLOAT |
The largest value of a label to keep in the output. |
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The new dataset consisting of all samples with labels in the specified region. |
sample = MachineLearning.DataSet.getSubsetInterval(dataSet, minValue, maxValue)
getSubsetLabels()
Return a new dataset object of a selected subset of the original dataset. This function allows the extraction of specific labels in case the LabelType is CLASSIFICATION.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
labels |
INT |
A vector of labels to keep in the output. |
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The new dataset consisting of all samples with the selected labels. |
sample = MachineLearning.DataSet.getSubsetLabels(dataSet, labels)
getType()
Returns the type of the data set, either CLASSIFICATION or REGRESSION.
| Name | Type | Description |
|---|---|---|
dataSet |
CONST_OBJECT MachineLearning.DataSet |
The input dataset. |
| Name | Type | Description |
|---|---|---|
type |
ENUM LabelType |
The type of the data set |
type = MachineLearning.getType(dataSet)
getWeight()
Return weight for a sample in the loaded set.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
index |
INT |
The index into the dataset. If left out all weights are returned. |
| Name | Type | Description |
|---|---|---|
weight |
AUTO |
The weight corresponding to the selected sample index or all weights if no index is supplied. |
weight = MachineLearning.DataSet.getWeight(dataSet, index)
normalize()
Apply a normalization matrix to a dataset object or another matrix. In both cases the dimensions must be compatible. Eg. the feature size of the dataset object or the amount of columns of the matrix must be equal to the columns of the normalization matrix.
| Name | Type | Description |
|---|---|---|
source |
OBJECT [API:DataFormat:] |
Either a dataset object or a matrix. |
normalization |
OBJECT Matrix |
A normalization matrix. Can be created using calculateNormalization or by manual composition. |
| Name | Type | Description |
|---|---|---|
normalized |
OBJECT [API:DataFormat:] |
A normalized version of the source input. |
normalized = MachineLearning.DataSet.normalize(source, normalization)
project()
Apply a projection matrix to a dataset object or another matrix. In both cases the dimensions must be compatible. Eg. the feature size of the dataset object or the amount of columns of the matrix must be equal to the columns of the projection matrix.
| Name | Type | Description |
|---|---|---|
source |
OBJECT [API:DataFormat:] |
Either a dataset object or a matrix. |
projection |
OBJECT Matrix |
A projection matrix. Can be created using calculateProjection or by manual composition. |
| Name | Type | Description |
|---|---|---|
projected |
OBJECT [API:DataFormat:] |
The projected version of the source input. |
projected = MachineLearning.DataSet.project(source, projection)
split()
Split a dataset object into two parts. The amount of samples in the larger set will be the same as the amount of samples in the smaller set times the input "factor". This means if factor is set to 3 that the first dataset object will be 3 times larger than the second. The sample selection is automatically randomized. To turn of randomization set the optional parameter "randomize" to false.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
factor |
INT |
The amount of samples in the major set compared to the minor set. |
randomize |
BOOL |
Select if samples should be randomized before split. Default is true. |
| Name | Type | Description |
|---|---|---|
major |
OBJECT MachineLearning.DataSet |
A new dataset containing the larger part of the samples. |
minor |
OBJECT MachineLearning.DataSet |
A new dataset containing the smaller part of the samples. |
major, minor = MachineLearning.DataSet.split(dataSet, 3)
toString()
Get a brief string description of the dataset. This is equal to the text shown in the debugger to describe the dataset.
| Name | Type | Description |
|---|---|---|
dataSet |
OBJECT MachineLearning.DataSet |
The input dataset |
| Name | Type | Description |
|---|---|---|
string |
STRING |
Description of the dataset |
print("Description: " .. MachineLearning.DataSet.toString(dataSet))
MachineLearning.Fisher
Fisher’s linear discriminant, sometimes called Linear Discriminant Analysis (LDA) is a method to find a vector which linearly separates two classes in an optimal way. This vector is found so that samples from different classes projected onto this vector end up as far apart a possible. For this reason Fisher can be used to understand what features of a data set have the most discriminating effect by looking at this vector. This is useful when trying to reduce the feature size input to another classifier without loosing too much performance.
Overview
Functions
clear()
Clear internal data of the classifier.
| Name | Type | Description |
|---|---|---|
fisher |
HANDLE |
The classifier instance to use. |
MachineLearning.Fisher.clear(fisher)
create()
Creates a handle for Fisher’s linear discriminant.
| Name | Type | Description |
|---|---|---|
fisher |
HANDLE |
The new Fisher handle |
lda = MachineLearning.Fisher.create()
getAccuracy()
Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.
| Name | Type | Description |
|---|---|---|
fisher |
HANDLE |
The classifier instance to use. |
dataSet |
OBJECT MachineLearning.DataSet |
The dataset to use |
| Name | Type | Description |
|---|---|---|
accuracy |
FLOAT |
The accuracy rate. Computed as correct classifications divided by total amount of samples. |
confusionMatrix |
OBJECT Matrix |
Confusion matrix for dataset and classifier. |
confusionMatrixLabels |
INT |
The label key for the confusion matrix. |
accuracy, confusionMatrix = MachineLearning.Fisher.getAccuracy(fisher, dataSet)
getFeatureCount()
Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.
| Name | Type | Description |
|---|---|---|
fisher |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
featureCount |
INT |
The amount of features per sample. |
trained = MachineLearning.Fisher.getFeatureCount(fisher)
getProjectionVector()
Returns the estimated projection direction for this classifier. This can be used to better understand what features are distinguishing when separating the objects.
| Name | Type | Description |
|---|---|---|
fisher |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
vector |
FLOAT |
A vector with the coefficients for projection. |
vector = MachineLearning.Fisher.getProjectionVector(fisher)
isTrained()
Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.
| Name | Type | Description |
|---|---|---|
fisher |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
trained |
BOOL |
True if the classifier is trained. |
trained = MachineLearning.Fisher.isTrained(fisher)
load()
Load a Fisher classifier from disk.
| Name | Type | Description |
|---|---|---|
path |
STRING |
The path to the classifier |
| Name | Type | Description |
|---|---|---|
fisher |
HANDLE |
The Fisher handle to the loaded object. |
fisher = MachineLearning.Fisher.load(path)
predict()
Classify a sample using the trained classifier.
| Name | Type | Description |
|---|---|---|
fisher |
HANDLE |
The classifier instance to use. |
sample |
OBJECT Matrix |
A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample. |
| Name | Type | Description |
|---|---|---|
class |
FLOAT |
Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels. |
class = MachineLearning.Fisher.predict(fisher, sample)
save()
Save a Fisher classifier to disk.
| Name | Type | Description |
|---|---|---|
fisher |
HANDLE |
The classifier instance to use |
path |
STRING |
The path at which to store the classifier |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if the file was successfully stored, false if storing failed. |
success = MachineLearning.Fisher.save(fisher, path)
toString()
Get a brief string description of the classifier. This is equal to the text shown in the debugger.
| Name | Type | Description |
|---|---|---|
fisher |
OBJECT MachineLearning.Fisher |
The input classifier data |
| Name | Type | Description |
|---|---|---|
string |
STRING |
Description of the classifier |
print("Description: " .. MachineLearning.Fisher.toString(fisher))
train()
Perform training on data supplied in a DataSet object.
| Name | Type | Description |
|---|---|---|
fisher |
HANDLE |
The classifier instance to use |
dataSet |
OBJECT MachineLearning.DataSet |
Input dataset |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if classifier was successfully trained. |
success = MachineLearning.Fisher.train(fisher, dataSet)
MachineLearning.KMeansClustering
k-Means Clustering is a technique mainly used to find structure in unordered data. It’s an iterative method which tries to group samples into clusters in a two step process. First a start solution is created by randomizing a number of cluster centers. Then features are assigned to clusters based on the feature distance to the cluster centers and secondly the center of each cluster is updated based on its feature members. This is iterated for a selectable number of cycles. Note that KMeansClustering in reality is a clustering algorithm and not really a classifier. It can be used for classification by checking what cluster a sample is closest to after training. Because of the clustering nature the default behavior is that the labels of the input data is updated with the result of the clustering operation. To disable this behavior set "updateInput" to false in setParameters.
Overview
Functions
clear()
Clear internal data of the classifier.
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The classifier instance to use. |
MachineLearning.KMeansClustering.clear(km)
create()
Creates a new KMeansClustering object.
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The new KMeansClustering handle |
km = MachineLearning.KMeansClustering.create()
getClusterCenters()
Get the resulting cluster centers for evaluation of the result.
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
clusters |
OBJECT Matrix |
The cluster centers with one position per row. |
clusters = MachineLearning.KMeansClustering.getClusterCenters(km)
getCompactness()
Get the compactness of the clustering. This is a measure on how well classes could be separated and is calculated as the average distance from all samples to their cluster centers.
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
compactness |
FLOAT |
The compactness of the clustering. |
compactness = MachineLearning.KMeansClustering.getCompactness(km)
getFeatureCount()
Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
featureCount |
INT |
The amount of features per sample. |
trained = MachineLearning.KMeansClustering.getFeatureCount(km)
isTrained()
Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
trained |
BOOL |
True if the classifier is trained. |
trained = MachineLearning.KMeansClustering.isTrained(km)
load()
Load a KMeansClustering classifier from disk.
| Name | Type | Description |
|---|---|---|
path |
STRING |
The path to the classifier |
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The KMeansClustering handle to the loaded object. |
km = MachineLearning.KMeansClustering.load(path)
predict()
Classify a sample using the trained classifier.
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The classifier instance to use. |
sample |
OBJECT Matrix |
A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample. |
| Name | Type | Description |
|---|---|---|
class |
FLOAT |
Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels. |
class = MachineLearning.KMeansClustering.predict(km, sample)
save()
Save a KMeansClustering classifier to disk.
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The classifier instance to use |
path |
STRING |
The path at which to store the classifier |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if the file was successfully stored, false if storing failed. |
success = MachineLearning.KMeansClustering.save(km, path)
setParameters()
Set parameters for how training should be done.
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The classifier instance to use |
numberOfClusters |
INT |
The number of clusters to fit to data (number of classes). |
initMethod |
ENUM InitMethod |
Select the way to initialize the algorithm. |
iterations |
INT |
Select the number of iterations to run the algorithm. Default is 100. |
updateInput |
BOOL |
Select if the labels of the dataset should be updated. Default is true. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successful, false if combination of parameters is unsupported. |
success = MachineLearning.KMeansClustering.setParameters(km, "RANDOM")
toString()
Get a brief string description of the classifier. This is equal to the text shown in the debugger.
| Name | Type | Description |
|---|---|---|
km |
The input classifier data |
| Name | Type | Description |
|---|---|---|
string |
STRING |
Description of the classifier |
print("Description: " .. MachineLearning.KMeansClustering.toString(km))
train()
Perform training on data supplied in a DataSet object.
| Name | Type | Description |
|---|---|---|
km |
HANDLE |
The classifier instance to use |
dataSet |
OBJECT MachineLearning.DataSet |
Input dataset |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if classifier was successfully trained. |
success = MachineLearning.KMeansClustering.train(km, dataSet)
MachineLearning.KNearestNeighbors
k Nearest Neighbors or kNN for short, is basically a voting scheme based on proximity. During training the training samples are collected and are themselves stored for later use during classification. During classification the features of a new sample are compared to features of the k closest samples from the training dataset. The classification is given by the majority vote of these k samples.
Overview
Functions
clear()
Clear internal data of the classifier.
| Name | Type | Description |
|---|---|---|
knn |
HANDLE |
The classifier instance to use. |
MachineLearning.KNearestNeighbors.clear(knn)
create()
Creates a new KNearestNeighbors handle
| Name | Type | Description |
|---|---|---|
knn |
HANDLE |
The new KNearestNeighbors handle |
knn = MachineLearning.KNearestNeighbors.create()
getAccuracy()
Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.
| Name | Type | Description |
|---|---|---|
knn |
HANDLE |
The classifier instance to use. |
dataSet |
OBJECT MachineLearning.DataSet |
The dataset to use |
| Name | Type | Description |
|---|---|---|
accuracy |
FLOAT |
The accuracy rate. Computed as correct classifications divided by total amount of samples. |
confusionMatrix |
OBJECT Matrix |
Confusion matrix for dataset and classifier. |
confusionMatrixLabels |
INT |
The label key for the confusion matrix. |
accuracy, confusionMatrix = MachineLearning.KNearestNeighbors.getAccuracy(knn, dataSet)
getFeatureCount()
Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.
| Name | Type | Description |
|---|---|---|
knn |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
featureCount |
INT |
The amount of features per sample. |
trained = MachineLearning.KNearestNeighbors.getFeatureCount(knn)
isTrained()
Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.
| Name | Type | Description |
|---|---|---|
knn |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
trained |
BOOL |
True if the classifier is trained. |
trained = MachineLearning.KNearestNeighbors.isTrained(knn)
load()
Load a KNearestNeighbors classifier from disk.
| Name | Type | Description |
|---|---|---|
path |
STRING |
The path to the classifier |
| Name | Type | Description |
|---|---|---|
knn |
HANDLE |
The KNearestNeighbors handle to the loaded object. |
knn = MachineLearning.KNearestNeighbors.load(path)
predict()
Classify a sample using the trained classifier.
| Name | Type | Description |
|---|---|---|
knn |
HANDLE |
The classifier instance to use. |
sample |
OBJECT Matrix |
A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample. |
| Name | Type | Description |
|---|---|---|
class |
FLOAT |
Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels. |
class = MachineLearning.KNearestNeighbors.predict(knn, sample)
save()
Save a KNearestNeighbors classifier to disk.
| Name | Type | Description |
|---|---|---|
knn |
HANDLE |
The classifier instance to use |
path |
STRING |
The path at which to store the classifier |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if the file was successfully stored, false if storing failed. |
success = MachineLearning.KNearestNeighbors.save(knn, path)
setParameters()
Set parameters for how training should be done.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The classifier instance to use |
numberOfNeighbors |
INT |
Number of neighbors to use when calculating. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successful, false if combination of parameters is unsupported. |
success = MachineLearning.KNearestNeighbors.setParameters(knn, 13)
toString()
Get a brief string description of the classifier. This is equal to the text shown in the debugger.
| Name | Type | Description |
|---|---|---|
knn |
The input classifier data |
| Name | Type | Description |
|---|---|---|
string |
STRING |
Description of the classifier |
print("Description: " .. MachineLearning.KNearestNeighbors.toString(knn))
train()
| Name | Type | Description |
|---|---|---|
knn |
HANDLE |
The classifier instance to use |
dataSet |
OBJECT MachineLearning.DataSet |
Input dataset |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if classifier was successfully trained. |
MachineLearning.KNearestNeighbors.train(knn, dataSet)
MachineLearning.NeuralNet
A neural network also known as Artificial Neural Net (ANN) or multi-layer perceptron (MLP) is a model initially created to mimic the function of neurons. Note that this is a shallow fully connected neural network model that can be trained on device. For larger Deep Neural Networks and Convolutional Networks see the DeepNeuralNetwork API. In a neural network there is an input layer, an output layer and a number of hidden layers. The input layer typically corresponds to the input features and the output layer to the output labels. In-between these two layers is an undecided number of hidden layers. The number of layers can be selected by the length of the "hiddenLayers" vector in the setParameters function and the amount of neurons in each layer by the value at each position in this vector. The first value corresponds to the layer closest to the input. Each neuron can be thought of as a simple decision point in the graph. How the decision is made is determined through training by means of back propagation on training data and by the selection of the activation function prior to training. One special feature of the neural network is that it can be trained incrementally. That is, it’s possible to train on different DataSet objects in sequence and get a final model with the accumulated result. The limitation of this is that only new samples of the same format can be added, no new features can be introduced between increments. Be sure to use the "clear" function if incremental training is not intended!
See also
Overview
Functions
clear()
Clear internal data of the classifier. Use this to forget previous samples and reset all network weights.
| Name | Type | Description |
|---|---|---|
nn |
HANDLE |
The classifier instance to use. |
MachineLearning.NeuralNet.clear(nn)
create()
Creates a new NeuralNet
| Name | Type | Description |
|---|---|---|
nn |
HANDLE |
The new NeuralNet handle |
nn = MachineLearning.NeuralNet.create()
getAccuracy()
Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.
| Name | Type | Description |
|---|---|---|
nn |
HANDLE |
The classifier instance to use. |
dataSet |
OBJECT MachineLearning.DataSet |
The dataset to use |
| Name | Type | Description |
|---|---|---|
accuracy |
FLOAT |
The accuracy rate. Computed as correct classifications divided by total amount of samples. |
confusionMatrix |
OBJECT Matrix |
Confusion matrix for dataset and classifier. |
confusionMatrixLabels |
INT |
The label key for the confusion matrix. |
accuracy, confusionMatrix = MachineLearning.NeuralNet.getAccuracy(nn, dataSet)
getFeatureCount()
Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.
| Name | Type | Description |
|---|---|---|
nn |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
featureCount |
INT |
The amount of features per sample. |
trained = MachineLearning.NeuralNet.getFeatureCount(nn)
isTrained()
Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.
| Name | Type | Description |
|---|---|---|
nn |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
trained |
BOOL |
True if the classifier is trained. |
trained = MachineLearning.NeuralNet.isTrained(nn)
load()
Load a NeuralNet classifier from disk.
| Name | Type | Description |
|---|---|---|
path |
STRING |
The path to the classifier |
| Name | Type | Description |
|---|---|---|
nn |
HANDLE |
The NeuralNet handle to the loaded object. |
nn = MachineLearning.NeuralNet.load(path)
predict()
Classify a sample using the trained classifier.
| Name | Type | Description |
|---|---|---|
nn |
HANDLE |
The classifier instance to use. |
sample |
OBJECT Matrix |
A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample. |
| Name | Type | Description |
|---|---|---|
class |
FLOAT |
Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels. |
class = MachineLearning.NeuralNet.predict(nn, sample)
save()
Save a NeuralNet classifier to disk.
| Name | Type | Description |
|---|---|---|
nn |
HANDLE |
The classifier instance to use |
path |
STRING |
The path at which to store the classifier |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if the file was successfully stored, false if storing failed. |
success = MachineLearning.NeuralNet.save(nn, path)
setParameters()
Set parameters for how training should be done.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The classifier instance to use |
hiddenLayers |
INT |
A vector specifying how many hidden neurons there should be in each layer. The first entry is closest to the input layer. |
activationFunction |
ENUM ActivationFunction |
Type of activation function to use in the perceptrons. If omitted SIGMOID is used. |
weightScale |
FLOAT |
Sets the weight scale for back propagation calculations. |
momentumScale |
FLOAT |
Sets the momentum scale for back propagation calculations. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successful, false if combination of parameters is unsupported. |
success = MachineLearning.NeuralNet.setParameters(nn, {3, 4}, "SIGMOID")
toString()
Get a brief string description of the classifier. This is equal to the text shown in the debugger.
| Name | Type | Description |
|---|---|---|
nn |
OBJECT MachineLearning.NeuralNet |
The input classifier data |
| Name | Type | Description |
|---|---|---|
string |
STRING |
Description of the classifier |
print("Description: " .. MachineLearning.NeuralNet.toString(nn))
train()
Perform training on data supplied in a DataSet object. Note that training is done incrementally. To start out from the beginning use "clear" or create a new NeuralNet handle.
| Name | Type | Description |
|---|---|---|
nn |
HANDLE |
The classifier instance to use |
dataSet |
OBJECT MachineLearning.DataSet |
Input dataset |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if classifier was successfully trained. |
success = MachineLearning.NeuralNet.train(nn, dataSet)
MachineLearning.RandomForest
The random forest method is a method based on decision trees. During training multiple decision trees are created based on subsets of the training dataset. During classification each tree is evaluated on the data and the majority vote wins.
Overview
Functions
clear()
Clear internal data of the classifier.
| Name | Type | Description |
|---|---|---|
rf |
HANDLE |
The classifier instance to use. |
MachineLearning.RandomForest.clear(rf)
create()
Creates a new RandomForest
| Name | Type | Description |
|---|---|---|
rf |
HANDLE |
The new RandomForest handle |
rf = MachineLearning.RandomForest.create()
getAccuracy()
Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.
| Name | Type | Description |
|---|---|---|
rf |
HANDLE |
The classifier instance to use. |
dataSet |
OBJECT MachineLearning.DataSet |
The data set to use |
| Name | Type | Description |
|---|---|---|
accuracy |
FLOAT |
The accuracy rate. Computed as correct classifications divided by total amount of samples. |
confusionMatrix |
OBJECT Matrix |
Confusion matrix for data set and classifier. |
confusionMatrixLabels |
INT |
The label key for the confusion matrix. |
accuracy, confusionMatrix = MachineLearning.RandomForest.getAccuracy(rf, dataSet)
getFeatureCount()
Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.
| Name | Type | Description |
|---|---|---|
rf |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
featureCount |
INT |
The amount of features per sample. |
trained = MachineLearning.RandomForest.getFeatureCount(rf)
isTrained()
Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.
| Name | Type | Description |
|---|---|---|
rf |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
trained |
BOOL |
True if the classifier is trained. |
trained = MachineLearning.RandomForest.isTrained(rf)
load()
Load a RandomForest classifier from disk.
| Name | Type | Description |
|---|---|---|
path |
STRING |
The path to the classifier |
| Name | Type | Description |
|---|---|---|
rf |
HANDLE |
The RandomForest handle to the loaded object. |
rf = MachineLearning.RandomForest.load(path)
predict()
Classify a sample using the trained classifier.
| Name | Type | Description |
|---|---|---|
rf |
HANDLE |
The classifier instance to use. |
sample |
OBJECT Matrix |
A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample. |
| Name | Type | Description |
|---|---|---|
class |
FLOAT |
Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels. |
class = MachineLearning.RandomForest.predict(rf, sample)
save()
Save a RandomForest classifier to disk.
| Name | Type | Description |
|---|---|---|
rf |
HANDLE |
The classifier instance to use |
path |
STRING |
The path at which to store the classifier |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if the file was successfully stored, false if storing failed. |
success = MachineLearning.RandomForest.save(rf, path)
setParameters()
Set parameters for how training should be done.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The classifier instance to use |
minSamplesPerNode |
INT |
If the number of samples in a node is less than this value the node will not be split. Default is 10. |
regressionAccuracy |
FLOAT |
Limit to determine when to stop splitting nodes for regression trees. Default is 0.01. |
activeVarCount |
INT |
The size of the subset of features at each tree node that are used to find the best split(s). If set to 0 it is automatically set to the square root of the number of samples. |
maxCategories |
INT |
In cases with more than 2 classes this limitation is used to reduce computation time at the cost of precision. Use a higher value for more precise results. Default is 10. |
maxTreeDepth |
INT |
If no other termination criteria stops the splitting this determines the maximum allowed depth of a tree. Default is 10. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successful, false if combination of parameters is unsupported. |
success = MachineLearning.RandomForest.setParameters(rf, ...)
toString()
Get a brief string description of the classifier. This is equal to the text shown in the debugger.
| Name | Type | Description |
|---|---|---|
rf |
OBJECT MachineLearning.RandomForest |
The input classifier data |
| Name | Type | Description |
|---|---|---|
string |
STRING |
Description of the classifier |
print("Description: " .. MachineLearning.RandomForest.toString(rf))
train()
Perform training on data supplied in a DataSet object.
| Name | Type | Description |
|---|---|---|
rf |
HANDLE |
The classifier instance to use |
dataSet |
OBJECT MachineLearning.DataSet |
Input dataset |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if classifier was successfully trained. |
success = MachineLearning.RandomForest.train(rf, dataSet)
MachineLearning.SupportVectorMachine
Support Vector Machines are used to distinguish multidimensional data by creating a decision boundary that maximizes the orthogonal distance between classes. A Support Vector Machine can be configured to support non-linear cases by using a non-linear kernel. A special case of the Support Vector Machine is the single class case where a classifier can be trained on samples only from one class to learn to recognize if new samples belong to this class or not. This requires training data set with only one input class.
Overview
Functions
clear()
Clear internal data of the classifier.
| Name | Type | Description |
|---|---|---|
svm |
HANDLE |
The classifier instance to use. |
MachineLearning.SupportVectorMachine.clear(svm)
create()
Creates a new SupportVectorMachine
| Name | Type | Description |
|---|---|---|
svm |
HANDLE |
The new SupportVectorMachine |
svm = MachineLearning.SupportVectorMachine.create()
getAccuracy()
Evaluate a classifier against a DataSet object by computing the predicted class and comparing it to the label supplied in the DataSet object. The "accuracy" returned will be the amount of correctly classified samples divided by the total amount of samples. The second output, the "confusionMatrix", is a NxN matrix. The final return value is a vector. This vector tells us what original label correspond to what row and column in the confusion matrix. In the NxN confusion matrix contains classification statistics. Each row corresponds to a label input and each column to a classification output. That is, if all classes have been correctly classified, there should only be non-zero elements along the diagonal of this matrix. For example a matrix of the following format C = [3 1, 2 4] labels = {1, 2} This means that the model had labels 1 and 2. For these labels the classification was tested on a total of 3+1+2+4 = 10 samples. Out of these 3+2 = 5 were classified as label one and 1+4 = 5 as label two. However, there were actually 3+1 = 4 samples of type one and 2+4 = 6 of type two in the input. To calculate the accuracy sum the diagonal, 3 + 4 = 7 and divide by the total amount of samples 10, which in this case gives an accuracy of 70%. It can also be useful to analyze other properties of this matrix. In this case inputs of type 2 are more likely to be classified as type 1 than type 1 being classified as type 2.
| Name | Type | Description |
|---|---|---|
svm |
HANDLE |
The classifier instance to use. |
dataSet |
OBJECT MachineLearning.DataSet |
The data set to use |
| Name | Type | Description |
|---|---|---|
accuracy |
FLOAT |
The accuracy rate. Computed as correct classifications divided by total amount of samples. |
confusionMatrix |
OBJECT Matrix |
Confusion matrix for data set and classifier. |
confusionMatrixLabels |
INT |
The label key for the confusion matrix. |
accuracy, confusionMatrix = MachineLearning.SupportVectorMachine.getAccuracy(svm, dataSet)
getFeatureCount()
Use to check what feature size the classifier was trained on. A classifier can only be used on new data with the same amount of features.
| Name | Type | Description |
|---|---|---|
svm |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
featureCount |
INT |
The amount of features per sample. |
trained = MachineLearning.SupportVectorMachine.getFeatureCount(svm)
isTrained()
Use to check if classifier has been trained successfully. If a classifier is trained it can be used to predict.
| Name | Type | Description |
|---|---|---|
svm |
HANDLE |
The classifier instance to use. |
| Name | Type | Description |
|---|---|---|
trained |
BOOL |
True if the classifier is trained. |
trained = MachineLearning.SupportVectorMachine.isTrained(svm)
load()
Load a SupportVectorMachine classifier from disk.
| Name | Type | Description |
|---|---|---|
path |
STRING |
The path to the classifier |
| Name | Type | Description |
|---|---|---|
svm |
HANDLE |
The SupportVectorMachine handle to the loaded object. |
svm = MachineLearning.SupportVectorMachine.load(path)
predict()
Classify a sample using the trained classifier.
| Name | Type | Description |
|---|---|---|
svm |
HANDLE |
The classifier instance to use. |
sample |
OBJECT Matrix |
A sample or a set of samples that are to be classified. Each row of the input matrix is considered one sample. |
| Name | Type | Description |
|---|---|---|
class |
FLOAT |
Predicted class output from the classifier. In case of a single sample input it’s a single value. For multi row input it’s a vector of class labels. |
class = MachineLearning.SupportVectorMachine.predict(svm, sample)
save()
Save a SupportVectorMachine classifier to disk.
| Name | Type | Description |
|---|---|---|
svm |
HANDLE |
The classifier instance to use |
path |
STRING |
The path at which to store the classifier |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if the file was successfully stored, false if storing failed. |
success = MachineLearning.SupportVectorMachine.save(svm, path)
setParameters()
Set parameters for how training should be done.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The classifier instance to use |
nu |
FLOAT |
Parameter commonly known as nu for Support Vector Machine optimization problems. It tweaks the flexibility/smoothing of the decision boundaries and the complexity of the final classifier. Should be a value in the range of 0 to 1. |
kernelType |
ENUM KernelType |
Type of kernel used in SupportVectorMachine computation. |
sigma |
FLOAT |
Standard deviation sigma for the GAUSSIAN kernel function. For the LINEAR KernelType this value is unused. |
singleClass |
BOOL |
Select this if only samples of one class is supplied. Learns to detect anomalies from this class. Not used in the regression case. |
c |
FLOAT |
SVM C parameter for regression problems. Not used in the classification case. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successful. |
success = MachineLearning.SupportVectorMachine.setParameters(svm, nu, kernelType, gamma)
toString()
Get a brief string description of the classifier. This is equal to the text shown in the debugger.
| Name | Type | Description |
|---|---|---|
svm |
The input classifier data |
| Name | Type | Description |
|---|---|---|
string |
STRING |
Description of the classifier |
print("Description: " .. MachineLearning.SupportVectorMachine.toString(svm))
train()
Perform training on data supplied in a DataSet object.
| Name | Type | Description |
|---|---|---|
svm |
HANDLE |
The classifier instance to use |
dataSet |
OBJECT MachineLearning.DataSet |
Input data set |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if classifier was successfully trained. Nil if dataSet is nil. |
MachineLearning.SupportVectorMachine.train(svm, dataSet)
Matrix
A 2D matrix of floating-point values.
Overview
add(), addConstant(), clone(), concatenate(), create(), createFromVector(), createIdentity(), determinant(), getColumn(), getRow(), getSize(), getValue(), invert(), max(), min(), multiply(), multiplyConstant(), norm(), setAll(), setColumn(), setRow(), setValue(), solve(), subtract(), sumColumns(), sumRows(), svd(), tile(), toImage(), toPoints(), toString(), toVector(), transpose()
Functions
add()
Adds two matrices of the same size.
| Name | Type | Description |
|---|---|---|
m1 |
CONST_OBJECT Matrix |
The first matrix to add |
m2 |
CONST_OBJECT Matrix |
The second matrix to add |
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The sum |
local matrix = Matrix.add(m1, m2)
addConstant()
Adds the value to each matrix element.
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The matrix to add to |
value |
FLOAT |
The value to add to each element in the matrix. |
Matrix.addConstant(matrix, value)
clone()
Duplicates the matrix.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The instance to use |
| Name | Type | Description |
|---|---|---|
clonedMatrix |
OBJECT Matrix |
The duplicated matrix |
local clonedMatrix = Matrix.clone(matrix)
concatenate()
Returns the concatenation of the two matrices.
| Name | Type | Description |
|---|---|---|
m1 |
CONST_OBJECT Matrix |
The first matrix to concatenate |
m2 |
CONST_OBJECT Matrix |
The second matrix to concatenate |
concatHorizontally |
BOOL |
If the concatenation shall be horizontally or vertically |
| Name | Type | Description |
|---|---|---|
concatMatrix |
OBJECT Matrix |
The new matrix |
local concatMatrix = Matrix.concatenate(m1, m2, concatHorizontally)
create()
Creates a new matrix.
| Name | Type | Description |
|---|---|---|
rows |
INT |
The number of rows |
cols |
INT |
The number of columns |
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The new matrix |
local matrix = Matrix.create(rows, cols)
createFromVector()
Creates a new matrix from a vector in row-major order.
| Name | Type | Description |
|---|---|---|
vector |
FLOAT |
The vector of elements to create the matrix from |
rows |
INT |
The number of rows |
cols |
INT |
The number of columns |
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The new matrix |
local matrix = Matrix.createFromVector(vector, rows, cols)
createIdentity()
Creates a new identity matrix.
| Name | Type | Description |
|---|---|---|
size |
INT |
The number of rows and columns |
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The new identity matrix |
local matrix = Matrix.createIdentity(size)
determinant()
Returns the determinant of the matrix.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix for which to calculate the determinant |
| Name | Type | Description |
|---|---|---|
det |
FLOAT |
The determinant of the matrix |
local det = Matrix.determinant(matrix)
getColumn()
Returns one or multiple columns of the matrix. The columns are returned as a MxK matrix, where M is the number of rows of the original matrix and K is the number of column indices in colIndex.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix from which to get the columns |
colIndex |
INT |
The index of the matrix columns |
| Name | Type | Description |
|---|---|---|
columns |
OBJECT Matrix |
The wanted matrix columns |
local columns = Matrix.getColumn(matrix, colIndex)
getRow()
Returns one or multiple rows of the matrix. The rows are returned as a KxN matrix, where N is the number of columns of the original matrix and K is the number of row indices in rowIndex.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix from which to get the rows |
rowIndex |
INT |
The index of the matrix rows |
| Name | Type | Description |
|---|---|---|
rows |
OBJECT Matrix |
The wanted matrix rows |
local rows = Matrix.getRow(matrix, rowIndex)
getSize()
Returns the number of rows and columns of the matrix.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The instance to use |
| Name | Type | Description |
|---|---|---|
rows |
INT |
The number of rows in the matrix |
cols |
INT |
The number of columns in the matrix |
local rows, columns= Matrix.getSize(matrix)
getValue()
Returns the value of the indexed matrix element. The first element has index (0,0).
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix in which to get a value |
rowIndex |
INT |
The row index of the matrix element |
colIndex |
INT |
The column index of the matrix element |
| Name | Type | Description |
|---|---|---|
value |
FLOAT |
The value |
local value = Matrix.getValue(matrix, rowIndex, colIndex)
invert()
Returns the inverse matrix.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The instance to use |
| Name | Type | Description |
|---|---|---|
inversedMatrix |
OBJECT Matrix |
The inverse matrix. |
local inversedMatrix = Matrix.invert(matrix)
max()
Returns the maximum value of the matrix.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix in which to find the maximum value |
| Name | Type | Description |
|---|---|---|
max |
FLOAT |
The maximum value of the matrix |
local max = Matrix.max(matrix)
min()
Returns the minimum value of the matrix.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix in which to find the minimum value |
| Name | Type | Description |
|---|---|---|
min |
FLOAT |
The minimum value of the matrix |
local min = Matrix.min(matrix)
multiply()
Multiplies two matrices. The first matrix must have the same number of columns as the second matrix has rows.
| Name | Type | Description |
|---|---|---|
m1 |
CONST_OBJECT Matrix |
The first matrix to multiply |
m2 |
CONST_OBJECT Matrix |
The second matrix to multiply |
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The matrix product |
local matrix = Matrix.multiply(m1, m2)
multiplyConstant()
Multiplies each matrix element with the value.
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The matrix to multiply by constant |
value |
FLOAT |
The value with which to multiply all elements in the matrix. |
Matrix.multiplyConstant(matrix, value)
norm()
Returns the Frobenius norm of the matrix, the square root of the sum of the squares of its elements.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix to calculate the norm for |
| Name | Type | Description |
|---|---|---|
norm |
FLOAT |
The norm of the matrix |
local norm = Matrix.norm(matrix)
setAll()
Sets the whole matrix to the same value.
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The matrix to set |
value |
FLOAT |
The value with which to set the whole matrix. |
Matrix.setAll(matrix, value)
setColumn()
Sets one or multiple columns of the matrix.
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The matrix in which to set the columns |
colIndex |
INT |
The indices of the matrix columns to set |
newColumn |
CONST_OBJECT Matrix |
The new matrix columns to set |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True is input is valid |
Matrix.setColumn(matrix, colIndex, newColumn)
setRow()
Sets one or multiple rows of the matrix.
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The matrix in which to set the rows |
rowIndex |
INT |
The index of the matrix rows to set |
newRow |
CONST_OBJECT Matrix |
The new matrix rows |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True is input is valid |
Matrix.setRow(matrix, rowIndex, newRow)
setValue()
Sets the value in the indexed matrix element. The first element has index (0,0).
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The matrix in which to set a value |
rowIndex |
INT |
The row index of the matrix element to change |
colIndex |
INT |
The column index of the matrix element to change |
value |
FLOAT |
The value to set |
Matrix.setValue(matrix, rowIndex, colIndex, value)
solve()
Computes the least squares solution to the equation system Ax = b. A is an NxM matrix. b is an Nx1 matrix. x is an Mx1 matrix and the solution to the equation system.
| Name | Type | Description |
|---|---|---|
a |
CONST_OBJECT Matrix |
NxM matrix describing the left side of the equation system. |
b |
CONST_OBJECT Matrix |
Nx1 matrix describing the right side of the equation system. |
| Name | Type | Description |
|---|---|---|
x |
OBJECT Matrix |
Mx1 matrix containing the solution to the equation system. |
residual |
FLOAT |
The average error by calculating (Ax - b).norm()/b.norm(). |
x, residual = Matrix.solve(a, b)
subtract()
Subtracts two matrices of the same size.
| Name | Type | Description |
|---|---|---|
m1 |
CONST_OBJECT Matrix |
The first matrix |
m2 |
CONST_OBJECT Matrix |
The matrix to subtract from the first |
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The difference |
local matrix = Matrix.subtract(m1, m2)
sumColumns()
Computes the sum of each column. The column sums are returned as a 1xN row matrix.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix in which to calculate the column sums |
| Name | Type | Description |
|---|---|---|
columnSums |
OBJECT Matrix |
The column sums of the matrix |
local columnSums = Matrix.sumColumns(matrix)
sumRows()
Computes the sum of each row. The row sums are returned as a Mx1 column matrix.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix in which to calculate the row sums |
| Name | Type | Description |
|---|---|---|
rowSums |
OBJECT Matrix |
The row sums of the matrix |
local rowSums = Matrix.sumRows(matrix)
svd()
Computes the singular value decomposition of an NxM matrix. U is the left singular vectors and U the right singular vectors corresponding to singular values S. In both U and V vectors are in the columns of each matrix such that matrix = U*diag(S)*V^T.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
Matrix to decompose. |
| Name | Type | Description |
|---|---|---|
u |
OBJECT Matrix |
The left singular vectors with each vector in a column. |
s |
FLOAT |
The singular values of the input matrix. |
v |
OBJECT Matrix |
The right singular vectors with each vector in a column. |
u, s, v = Matrix.svd(matrix)
tile()
Returns an n-by-m tiling of the matrix.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix to tile |
n |
INT |
The number of vertical repetitions |
m |
INT |
The number of horizontal repetitions |
| Name | Type | Description |
|---|---|---|
tileMatrix |
OBJECT Matrix |
The new matrix |
local tileMatrix = Matrix.tile(matrix, n, m)
toImage()
Converts a matrix to a float64 image.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
Matrix to convert to image. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
Image created from the matrix. |
image = Matrix.toImage(matrix)
toPoints()
Converts a matrix to a vector of 2D or 3D points.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
Matrix to convert to vector of points. |
storedInColumns |
BOOL |
True if the points are in the columns of the matrix, false if in the rows of the matrix. |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
Points created from the matrix. |
points = Matrix.toPoints(matrix, storedInColumns)
toString()
Get a string representation of the matrix.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
Input matrix |
| Name | Type | Description |
|---|---|---|
str |
STRING |
String representation of the matrix |
print("The matrix is: " .. Matrix.toString(matrix))
toVector()
Returns all elements of the matrix as vector in row-major order.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
The matrix |
| Name | Type | Description |
|---|---|---|
vector |
FLOAT |
Matrix elements as vector in row-major order |
local vector = Matrix.toVector(matrix)
Mesh
Object for a 3D surface represented by a triangle mesh. The mesh consists of a vector of vertices (3D points) and vector of triplets defining the 3 vertex indices of each triangle. For each vertex, there can also be a 3D normal and an intensity or RGBA color component. There are two types of triangle representations indexed triangles or separated triangles. In the case of indexed triangles a vertex can be used by several triangles, and in the case of separated triangles a vertex can only be used by a single triangle. In some cases a combination of both representations is also possible. Unless known it might be unclear what representation the mesh has. The representation has consequences in how algorithms perform; an example is the connected components algorithm, with separated triangles none of the triangles share vertex indices so only single connections (1 triangle) can be found. In this case a search radius must be specified to search for nearby vertices.
Overview
Functions
clone()
Returns a duplicated instance of the input mesh. This is a full copy and might be very slow dependent on the mesh size.
| Name | Type | Description |
|---|---|---|
inputMesh |
CONST_OBJECT Mesh |
The mesh to clone. |
| Name | Type | Description |
|---|---|---|
clone |
OBJECT Mesh |
The new cloned mesh object. |
local clone = Mesh.clone(inputMesh)
create()
Creates a new empty mesh object
| Name | Type | Description |
|---|---|---|
newMesh |
OBJECT Mesh |
The newly created mesh |
local newMesh = Mesh.create()
getTriangleCount()
Returns the number of triangles in the mesh.
| Name | Type | Description |
|---|---|---|
mesh |
CONST_OBJECT Mesh |
The mesh. |
| Name | Type | Description |
|---|---|---|
triangleCount |
INT |
The mesh number of triangles. |
local triangleCount = Mesh.getTriangleCount(mesh)
getVertexCount()
Returns the number of vertices in the mesh.
| Name | Type | Description |
|---|---|---|
mesh |
CONST_OBJECT Mesh |
The mesh. |
| Name | Type | Description |
|---|---|---|
vertexCount |
INT |
The mesh number of vertices. |
local vertexCount = Mesh.getVertexCount(mesh)
hasColor()
Check if the mesh contains colors.
| Name | Type | Description |
|---|---|---|
mesh |
CONST_OBJECT Mesh |
The mesh. |
| Name | Type | Description |
|---|---|---|
foundColor |
BOOL |
True if the mesh contains colors. |
local foundColor = Mesh.hasColor(mesh)
hasIntensity()
Check if the mesh contains intensities.
| Name | Type | Description |
|---|---|---|
mesh |
CONST_OBJECT Mesh |
The mesh. |
| Name | Type | Description |
|---|---|---|
foundIntensity |
BOOL |
True if the mesh contains intensities. |
local foundIntensity = Mesh.hasIntensity(mesh)
hasNormals()
Check if the mesh contains normals.
| Name | Type | Description |
|---|---|---|
mesh |
CONST_OBJECT Mesh |
The mesh. |
| Name | Type | Description |
|---|---|---|
foundNormals |
BOOL |
True if the mesh contains normals. |
local foundNormals = Mesh.hasNormals(mesh)
hasTextureCoordinates()
Check if the mesh contains texture coordinates.
| Name | Type | Description |
|---|---|---|
mesh |
CONST_OBJECT Mesh |
The mesh. |
| Name | Type | Description |
|---|---|---|
foundTextureCoordinates |
BOOL |
True if the mesh contains texture coordinates. |
local foundTextureCoordinates = Mesh.hasTextureCoordinates(mesh)
load()
Loads a mesh from the specified file path. The format is defined by the file extension: .ply: Polygon File Format .json: JSON .msgpack: MessagePack
| Name | Type | Description |
|---|---|---|
filePath |
STRING |
The path and name of the file to load the mesh from. |
| Name | Type | Description |
|---|---|---|
mesh |
OBJECT Mesh |
The mesh object. |
mesh = Mesh.load("private/mesh.ply")
save()
Saves a mesh to the specified file path. Overwrites the file if it already exists. The format is defined by the file extension: .ply: Polygon File Format (Optional useBinary parameter is supported). .json: JSON (Optional useBinary parameter not supported). .msgpack: MessagePack (Optional useBinary parameter not supported).
| Name | Type | Description |
|---|---|---|
mesh |
CONST_OBJECT Mesh |
The Mesh object which is saved. |
filepath |
STRING |
The path and name of the file to save the mesh to. |
useBinary |
BOOL |
Optional parameter that can only be used when saving to .ply format. If true write the ply data (except the header) in binary instead of ASCII. Default is true. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if the mesh has been successfully saved. |
local success = Mesh.save(mesh, "private/mesh.ply", useBinary)
toString()
Gets a user-friendly string description of the mesh, containing important properties.
| Name | Type | Description |
|---|---|---|
mesh |
CONST_OBJECT Mesh |
The mesh to describe. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the mesh. |
str = Mesh.toString(mesh)
Monitor
Provides monitoring functionality
Monitor.App
Provides monitoring access to the status info of an app like app status and memory usage.
Overview
Functions
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
appName |
STRING |
The name of the app to monitor. |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
handle to the App-monitor. |
handle = Monitor.App.create("HelloWorld")
getMemoryUsage()
Get the script interpreter memory usage of the app.
| Name | Type | Description |
|---|---|---|
monitorHandle |
HANDLE |
Handle to the App-monitor. |
| Name | Type | Description |
|---|---|---|
usedBytes |
INT |
Memory-bytes used by the script interpreter of this app. |
Monitor.App.getMemoryUsage(handle)
getPrivateDataUsage()
Get the AppData usage of the app.
| Name | Type | Description |
|---|---|---|
monitorHandle |
HANDLE |
Handle to the App-monitor. |
| Name | Type | Description |
|---|---|---|
usedBytes |
INT |
Bytes in the AppData folder used by this app. |
capacityBytes |
INT |
Total capacity of the AppData folder for all apps in bytes. |
appDataUsage |
FLOAT |
The used bytes of the app in percent of the whole capactiy of the AppData folder. |
Monitor.App.getPrivateDataUsage(handle)
getStatusInfo()
Get the status of the app.
| Name | Type | Description |
|---|---|---|
monitorHandle |
HANDLE |
Handle to the App-monitor. |
| Name | Type | Description |
|---|---|---|
state |
ENUM AppStatus |
Status of the app. |
additionalInfo |
STRING |
Additional info to the status of the App. This can be the crash reason in case of a crash. |
Monitor.App.getStatusInfo(handle)
Monitor.CPU
Provides monitoring access to CPU load in sum and for each core.
Functions
create()
Creates a new instance. Can be instantiated multiple times.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
handle to the CPU-monitor. |
handle = Monitor.CPU.create()
getLoad()
Get the current load of the CPU.
| Name | Type | Description |
|---|---|---|
monitorHandle |
HANDLE |
Handle to the CPU-monitor. |
| Name | Type | Description |
|---|---|---|
overallLoad |
FLOAT |
The overall CPU load in percent. |
detailedLoad |
FLOAT |
The load of each CPU core in percent. |
Monitor.CPU.getLoad(handle)
Monitor.Memory
Provides monitoring access to the RAM memory usage of the device.
Overview
Functions
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
handle to the Memory-monitor. |
handle = Monitor.Memory.create()
getUsage()
Get the current memory usage.
| Name | Type | Description |
|---|---|---|
monitorHandle |
HANDLE |
Handle to the Memory-monitor. |
| Name | Type | Description |
|---|---|---|
usedBytes |
INT |
Currently used bytes. |
capacityBytes |
INT |
Memory capacity in bytes. |
memUsage |
FLOAT |
The memory used in percent of the whole capacity. |
Monitor.Memory.getUsage(handle)
Monitor.Network
Provides monitoring access to the network interface load of each interface or all interfaces together.
Functions
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
interface |
ENUM EthernetInterfaces |
The interface to monitor. Use 'ALL' to monitor all interfaces. |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the Network-monitor. Will return nil if the interface is not valid, or if no statistics can be loaded. |
Monitor.Network.create("ETH1")
getLoad()
Get the current network load.
| Name | Type | Description |
|---|---|---|
monitorHandle |
HANDLE |
Handle to the Network-monitor. |
| Name | Type | Description |
|---|---|---|
sentBytesPerSec |
INT |
Current bytes sent per second. |
receivedBytesPerSec |
INT |
Current bytes received per second. |
Monitor.Network.getLoad(handle)
NTPClient
Offers access to control the NPTClient of the device. There can be only one NPTClient running on one defined ethernet interface. Also there can be only one controlling the NTPClient, therefore the handle can only be instantiated once. If the handle is destructed, the last NTP configuration keeps active and NTPClient stays running if activated.
Overview
Functions
create()
Creates a handle to the NTPClient. Only one instance can be acquired.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle for the NTPClient. nil if there is already another instance or if the device has no NTP functionality. |
handle = NTPClient.create()
setApplyEnabled()
Enables or disables the application of the timestamp received by NTP to the system time.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the NTPClient object. |
state |
BOOL |
Set to true to apply NTP time to system time. If set to false the NTP time is just printed to the log. |
NTPClient.setApplyEnabled(handle, false)
setInterface()
Sets the interface to use for connecting.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the NTPClient object. |
ifName |
ENUM EthernetInterfaces |
One of the available interfaces |
NTPClient.setInterface(handle, "ETH1")
setPeriodicUpdateEnabled()
Enables or disables periodic NTP requests. Per default, the periodic update is enabled if time source is set to 'NTP'.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the NTPClient object. |
state |
BOOL |
Set to true to request time updates from NTP in 10 minute intervals. If set to false you must trigger requests manually by using startManualRequest(). |
NTPClient.setPeriodicUpdateEnabled(handle, true)
setServerAddress()
Sets the NTP server address.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the NTPClient object. |
address |
STRING |
Address of the NTP server. |
NTPClient.setServerAddress(handle, "192.168.0.1")
setServerPort()
Sets the NTP server port.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the NTPClient object. |
port |
INT |
Port of the NTP server. |
NTPClient.setServerPort(handle, 12345)
setTimeSource()
Configures the source of the system time.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the NTPClient object. |
source |
ENUM TimeSource |
System time source. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully set, false if not. |
success = NTPClient.setTimeSource(handle, "MANUAL")
setTimeout()
Sets the timeout for NTP requests in milliseconds.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the NTPClient object. |
timeout |
INT |
Timeout in milliseconds. |
NTPClient.setTimeout(handle, 5000)
startManualRequest()
Trigger a NTP request manually now. TimeSource needs to be set to 'NTP' so that this function works, otherwise returns false. This function does not block until the request is over, it just triggers an asynchronous start of a request.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the NTPClient object. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if request was successfully triggered, false if not possible because not configured to NTP or internal error. |
success = NTPClient.startManualRequest(handle)
OPCUA
Provides OPC UA server functionality. OPC UA Overview: The OPC Unified Architecture (UA), released in 2008, is a platform independent service-oriented architecture that integrates all the functionality of the individual OPC Classic specifications into one extensible framework. It is developed by the OPC Foundation. See reference document 1 for more details about the protocol. API Overview: This API implements all the functions that are required to start a OPC UA server. It allows to create nodes of different classes, e.g. variables, objects or methods, and connect them via references to build up a custom information model. Nodes are grouped together into a namespace. A server can have one or more namespaces. The provided functions can be categorized into three groups: 1. Server management and server configuration: OPCUA.Server.* 2. Creating and managing namespaces: OPCUA.Server.Namespace.* 3. Creating, managing and using nodes and references: OPCUA.Server.Node.* According to internal, unofficial tests, this OPC UA CROWN can be used to fulfill the following OPC UA Profiles: - Nano Embedded Device Server Profile (Compliance Test Tool version 1.3.340.380) - SecurityPolicy - None (requires openSSL library) - SecurityPolicy - Basic128Rsa15 (requires openSSL library) - SecurityPolicy - Basic256 (requires openSSL library) - SecurityPolicy - Basic256Sha256 (requires openSSL library) So far, no other profiles are fulfilled. Please note that profile compliance was tested with a reference server implementation using this OPC UA CROWN. Other server implementations using this CROWN need to be tested separately according to the official OPC UA certification procedure in order to officially claim compliance. The server allows the following user token policies: - anonymous - user name / password So far, no other user token policies (e.g., x509, token, …) are supported. Limitations: - The server does not fulfill the other OPC UA Profiles for servers: Micro Embedded Device Server, Embedded UA Server and Standard UA Server. - loading of NodeSet2 files supported only if server supports the objects and value in the file (e.g., it does not support loading of 2-dimensional values) - If a target device platform does not provide openSSL library, then all security features are disabled. - Only one transport type is supported: UA TCP - UA Secure Conversation - UA Binary. - It is possible to use custom structured data types, however these types must be loaded from XML files. Access to these data types can be done through Value CROWN. - Only one-dimensional arrays are supported. - Unsupported service sets: — NodeManagement Service Set: AddNodes, AddReferences, DeleteNodes, DeleteReferences — View Service Set: RegisterNodes, UnregisterNodes, Query Service Set, QueryFirst, QueryNext — Attribute Service Set: HistoryRead, HistoryUpdate - Unsupported built-in data types: — XmlElement — ExtensionObject (but enumerations are supported) — DataValue — Variant — nested DiagnosticInfos Reference Documents: 1. OPC Unified Architecture Specification, Parts 1-13, https://opcfoundation.org/developer-tools/specifications-unified-architecture
OPCUA.Server
Provides OPC UA Server functionality.
Overview
Functions
create()
Create a new OPC UA Server instance. Server address space is in a default state (i.e., a pristine NS0). Network communication is not active.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server. Currently, it is only possible to create a single instance handle. Fails with return value nil when another instance handle already exists. |
handle = OPCUA.Server.create()
getNamespace()
Retrieve a namespace from the server
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
index |
INT |
The index of the namespace to get. |
| Name | Type | Description |
|---|---|---|
namespace |
OBJECT OPCUA.Server.Namespace |
The requested namespace or nil if the namespace can not be found |
loadNodeSet2File()
Load a NodeSet2 XML file. This method can be called multiple times to load different files. In case of an error during loading (e.g, due to invalid file contents), loading stops when the error is encountered. Consider using resetAddressSpace() to remove partially loaded files from address space.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
fileName |
STRING |
NodeSet2 XML file to load |
| Name | Type | Description |
|---|---|---|
status |
BOOL |
True if loaded successfully, false otherwise |
resetAddressSpace()
Reset the OPC UA server. Whole address space is reset to default state (i.e., a pristine NS0). All CROWN instances to existing nodes become invalid. Other settings (e.g., network settings) are not affected by reset. Call reset() only when server is stopped.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true when the OPC UA server has been reset successfully, false if an error occurred. |
success = OPCUA.Server.resetAddressSpace(handle)
setApplicationName()
Set the name of the application. This name is shown to clients as the name of the server and should describe what the server actually does.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
name |
STRING |
Name of the application that is shown to clients |
OPCUA.Server.setApplicationName(handle, "MyApplication")
setApplicationURI()
Set the Application URI. Call to this function is optional. The Application URI of a server represents a globally-unique logical name for a Server within the scope of the network in which it is installed. This identifier should be a fully qualified domain name; however, it may be a GUID or similar construct that ensures global uniqueness. If this function is not called, the following default ApplicationURI urn://sick.com/opc/ua/serial/${DEVICE_PRODUCT}/${SERIAL_NUMBER} is used, where the variable ${DEVICE_PRODUCT} is replaced by the device name and ${SERIAL_NUMBER} is replaced by the serial number. Example for a SIM4000 device: urn://sick.com/opc/ua/serial/SIM4000/12345678
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
uri |
STRING |
Application URI. Can be chosen freely, but SICK recommends to use the following format: urn://sick.com/opc/ua/app/[product/]unique_identifier. The unique_identifier should not change on device reset. |
OPCUA.Server.setApplicationURI(handle, "urn://sick.com/opc/ua/app/sim/sim4000/my_application_uid")
setConfiguration()
Set a ServerConfiguration. Please note that server copies the configuration when this function is called.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
config |
The configuration for the OPC UA Server |
setInterface()
Set the interface on which the server should listen. Call to this function is optional. By default, server listens all interfaces. On multi-homed hosts, it is recommended to bind the server to one specific interface. Otherwise, one OPC UA EndPoint is created for each IP address and the client has to select the right one manually. This function will become deprecated soon. See description of OPCUA CROWN for more details.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
ifName |
ENUM EthernetInterfaces |
One of the available interfaces |
OPCUA.Server.setInterface(handle, "ETH1")
setNamespaces()
Set all OPC UA Namespaces the server should use. Please note that his removes any nodes that are neither in standard namespace NS0 nor in the namespaces parameter.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
namespaces |
OBJECT OPCUA.Server.Namespace |
The Namespace objects the server should use. All Namespaces which have been added previously are removed. |
OPCUA.Server.setNamespaces(handle, {namespace1, namespace2})
setPort()
Set the port on which the server should listen. Call to this function is optional. By default, port is 4840. This function will become deprecated soon. See description of OPCUA CROWN for more details.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
port |
INT |
The server port between 1 and 65535. |
OPCUA.Server.setPort(handle, 4840)
start()
Start the network communication. After a successful start, OPC UA clients can connect to server via network.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true when the OPC UA server has been started successfully, false if an error occurred. |
success = OPCUA.Server.start(handle)
stop()
Stop the OPC UA server’s network communication.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Server |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Is true when the OPC UA server has been stopped successfully, false if an error occurred. |
OPCUA.Server.stop(handle)
OPCUA.Server.EndpointConfiguration
An EndpointConfiguration consists of (1) a certificate store configuration, (2) a non-empty set of SecurityConfigurations, (3) a boolean flag for enabling application authentication, (4) a reference to an UserTokenDatabase and (5) a bind URL.
Overview
Functions
create()
Create an EndpointConfiguration with default values. Default values are: (1) no certificate store, (2) one SecurityConfiguration with default values, (3) application authentication = disabled, (4) empty UserTokenDatabase (5) interface ="ALL" and (6) port = 4840.
| Name | Type | Description |
|---|---|---|
config |
Configuration with default values |
obj = OPCUA.EndpointConfiguration.create()
enableApplicationAuthentication()
Enable or disable application authentication.
| Name | Type | Description |
|---|---|---|
config |
The configuration whose application authentication should be enabled / disabled. |
|
enabled |
BOOL |
Set to true to enable application authentication. |
setCertificateStoreConfiguration()
Sets the CertificateStoreConfiguration.
| Name | Type | Description |
|---|---|---|
config |
The configuration whose CertificateStoreConfiguration should be set. |
|
certificateStoreConfiguration |
OBJECT [API:DataFormat:] |
The CertificateStoreConfiguration to set. Pass nil to indicate that no certificate store should be used. |
setInterface()
Sets the interface to bind the Endpoint to. If interface is set to "ALL", then the Endpoint binds to all network interfaces. In such a case there can only be one EndpointConfiguration in a ServerConfiguration.
| Name | Type | Description |
|---|---|---|
config |
The configuration whose bind URL should be set. |
|
interface |
ENUM EthernetInterfaces |
The interface to bind to (e.g., ETH1). |
setPort()
Sets the port to listen to.
| Name | Type | Description |
|---|---|---|
config |
The configuration whose bind URL should be set. |
|
port |
INT |
The server port between 1 and 65535. |
setSecurityConfigurations()
Sets the SecurityConfigurations.
| Name | Type | Description |
|---|---|---|
config |
The configuration whose SecurityConfigurations should be set. |
|
securityConfigurations |
Non-empty set of security configurations. |
setUserTokenDatabase()
Sets the UserTokenDatabase. Please note that the behavior of this setter only stores a reference to the UserTokenDatabase. This allows the sharing of one UserTokenDatabase among multiple EndPoints. Consequences are: (1) if a server S is configured to use a UserTokenDatabase instance U and U.addUserPassword("x", "y") is called, then S immediately accepts the user x.
| Name | Type | Description |
|---|---|---|
config |
The configuration whose UserTokenDatabase should be set. |
|
userTokenDatabase |
The UserTokenDatabase to set. Pass nil to indicate that no UserTokenDatabase should be used. |
OPCUA.Server.FileCertificateStoreConfiguration
FileCertificateStoreConfiguration contains information about a file-based certificate store. The only parameter of this certificate store type is the root directory. All other directories should be created with fixed names below root directory. Directory layout: - ${rootDir}/issuer/certs: The issuer directory contains non-trusted issuer / certificate authority (CA) certificates - ${rootDir}/issuer/crl: The issuer CRL directory contains the CRLs of the CA certs from issuer directory. - ${rootDir}/trusted/certs: The trusted directory contains trusted CA certificates and self-signed certificates. - ${rootDir}/trusted/crl: The trusted CRL directory contains the CRLs of the CA certs from trusted directory. Please note that FileCertificateStoreConfiguration only holds the information where to look for certificates. The app developer is responsible for ensuring that the directories exist and contain the required files.
Overview
Functions
create()
Creates a file store configuration with root directory = "."
| Name | Type | Description |
|---|---|---|
config |
The created FileCertificateStoreConfiguration instance. |
obj = OPCUA.FileCertificateStoreConfiguration.create()
setRootDirectory()
Sets the root directory.
| Name | Type | Description |
|---|---|---|
database |
The configuration whose root directory should be set. |
|
rootDir |
STRING |
The root directory. |
OPCUA.Server.Namespace
Represents a OPC UA namespace. A OPC UA Server can work with one or more user defined namespaces. Namespaces can be added to the server using the function OPCUA.Server.setNamespaces.
Functions
create()
Create a new OPC UA Namespace instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Namespace |
handle = OPCUA.Server.Namespace.create()
getNode()
Retrieve an OPC UA node that is inside the namespace.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Namespace |
idType |
ENUM NodeIDType |
Type of the ID |
id |
AUTO |
The ID of the Node to get |
| Name | Type | Description |
|---|---|---|
node |
OBJECT OPCUA.Server.Node |
The requested node or nil if the node can not be found |
local node = OPCUA.Server.Namespace.getNode(handle, "STRING", "MySimpleVariableNode")
getNodeFromStandardNamespace()
Retrieve a node that is part of the standard namespace NS0. The available Node IDs are listed in the OPC Unified Architecture Specification, Part 6: Mappings, Annex B: OPC UA Nodeset.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Namespace |
idType |
ENUM NodeIDType |
Type of the ID |
id |
AUTO |
The ID of the Node to get |
| Name | Type | Description |
|---|---|---|
node |
OBJECT OPCUA.Server.Node |
The requested node or nil if the node can not be found |
local node = OPCUA.Server.Namespace.getNodeFromStandardNamespace(handle, "NUMERIC", 5)
setIndex()
Sets the index of the namespace. Calling this function. By default, namespace indices are assigned automatically in the order of namespace creation, starting with index 2.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Namespace |
index |
INT |
The namespace index to use. Must not be in use by any other namespace. |
url |
STRING |
URL that identifies the namespace, is shown to clients for a better understanding of the namespace index. Should start with urn://. If not provided, default is device_product/namespace_index_as_string |
OPCUA.Server.Namespace.setIndex(handle, 3)
setNodes()
Set all nodes that belong to this namespace.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Namespace |
nodes |
OBJECT OPCUA.Server.Node |
All nodes that should belong to this namespace, including the root node. |
OPCUA.Server.Namespace.setNodes(handle, {node1, node2})
setRootNode()
Sets the root node of the namespace.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Namespace |
root |
OBJECT OPCUA.Server.Node |
The root node. It is recommended to use a folder node as root |
suspensionFolder |
OBJECT OPCUA.Server.Node |
Optional. The node (folder) that is the parent node of root. Default is the global root node of the OPC UA default namespace |
OPCUA.Server.Namespace.setRootNode(handle, rootNode)
OPCUA.Server.Node
Represents a single node in the address space of a OPC UA server. Some node types (of type "Variable" and "VariableType") contain values. These can be accessed via getValue(), setValue() and getValueHandle(). For more information on value handling see OPCUA.Server.Value CROWN.
Overview
addReference(), callMethod(), create(), createEventParameters(), createMethodParameters(), deregister(), getValue(), getValueHandle(), notifyEvent(), register(), registerCallbacks(), setAccessLevel(), setArrayDimensions(), setBrowseName(), setDataType(), setDataTypeByNode(), setDescription(), setDisplayName(), setEnumChoices(), setID(), setMethodBehavior(), setTypeDefinition(), setTypeDefinitionByNode(), setValue()
Functions
addReference()
Create a reference from this node to another node. An inverse reference from the target node to this node is created automatically, if possible. Example: When creating a reference from folderNode to otherNode with reference type "Organizes", otherNode automatically gets an inverse reference of type "OrganizedBy" to folderNode.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
type |
ENUM ReferenceType |
Type of the reference between this node and the target node |
other |
OBJECT OPCUA.Server.Node |
The target node to which the reference points |
OPCUA.Server.Node.addReference(folderHandle, "ORGANIZES", simpleVariable)
callMethod()
Call the method on the node
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
parameters |
OBJECT OPCUA.Server.Value |
The parameters that should be used for the call. Might be omitted (nil) if there are no parameters. |
| Name | Type | Description |
|---|---|---|
returnValues |
OBJECT OPCUA.Server.Value |
The return values of the call. Might be omitted (nil) if there are no return values. |
OPCUA.Server.Node.callMethod(handle, {paramValueHandle1, paramValueHandle2}) -- This method takes two parameters
create()
Creates a new OPC UA node.
| Name | Type | Description |
|---|---|---|
class |
ENUM NodeClass |
Class of the node |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
handle = OPCUA.Server.Node.create("VARIABLE")
createEventParameters()
Create the parameters for an event; only works for event type nodes
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
| Name | Type | Description |
|---|---|---|
parameters |
OBJECT OPCUA.Server.Value |
The parameters of the call. Might be omitted (nil) if there are no parameters. |
OPCUA.Server.Node.createEventParameters(handle)
createMethodParameters()
Create the default parameters for a method
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
| Name | Type | Description |
|---|---|---|
parameters |
OBJECT OPCUA.Server.Value |
The return values of the call. Might be omitted (nil) if there are no return values. |
OPCUA.Server.Node.createMethodParameters(handle)
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
getValue()
Gets the current value of the OPC UA node. Only works if NodeClass is VARIABLE or OBJECT.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
| Name | Type | Description |
|---|---|---|
value |
AUTO |
The value of the node |
local value = OPCUA.Server.Node.getValue(handle)
getValueHandle()
Gets the current value (a handle for the value) of the OPC UA node. Only works if NodeClass is VARIABLE or VARIABLE_TYPE.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
| Name | Type | Description |
|---|---|---|
value |
HANDLE |
The value of the node |
local value = OPCUA.Server.Node.getValueHandle(handle)
notifyEvent()
Let the node notify the given event if it is a source of this event. (All Notifier nodes are informed)
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
fireEventType |
OBJECT OPCUA.Server.Node |
Type of the event to be notified (instance of EventType (ObjectType)) |
severity |
ENUM EventSeverity |
How severe is the event to be notified |
message |
STRING |
Message to be transferred (human readable) |
parameters |
OBJECT OPCUA.Server.Node |
The additional parameters of the event |
OPCUA.Server.Node.notifyEvent(handle, eventTypeNode, "MEDIUM", "demoEvent occurred.")
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
registerCallbacks()
Register functions that should be called to get or set the value of the OPC UA node. The getter function has the following signature: no input parameters. Getter returns a value of type OPCUA.Server.Value. For legacy compatibility it is still possible to return builtin values. It is strongly recommended to return OPCUA.Server.Value, because legacy behaviour is deprecated and will be removed soon. The setter function has the following signature: one OPCUA.Server.Value value as input parameter. Setter returns true if value was set successful, false otherwise. Please note that OPCUA.Server.Value is used to enable setting of complex types (e.g., structures or unions). There is not guarantee on the number of getter/setter callback invocations by internal mechanism. In general, lua callbacks should not be used for runtime performace crtical features.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
getter |
STRING |
Name of the Getter function |
setter |
STRING |
Name of the Setter function. The function must return a bool value that indicates success (true) or failure (false) |
OPCUA.Server.Node.registerCallbacks(handle, getter, setter)
setAccessLevel()
Function to set access level to values of VARIABLE nodes.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
accessLevel |
ENUM AccessLevel |
Access level for the variable |
OPCUA.Server.Node.setAccessLevel(handle, "READ_WRITE")
setArrayDimensions()
Specify the size of an array. For each dimension of the array, a corresponding value in the list specifies the length of the dimension. Currently, only one-dimensional arrays are supported. A data type must be set before setting the dimensions.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
dimensions |
INT |
The dimensions with specified length. If the first dimension is zero, scalar value is used. |
OPCUA.Server.Node.setArrayDimensions(handle, {3})
setBrowseName()
Sets the name of the node that is used for browsing.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
browseName |
STRING |
The browse name to use |
OPCUA.Server.Node.setBrowseName(handle, "MySimpleVariableNode")
setDataType()
Set the data type of the OPC UA node to one of the standard node types. Arbitrary types can be set by using the function setDataTypeByNode instead. Only applies to nodes of type VARIABLE or VARIABLE_TYPE.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
type |
ENUM DataType |
The type of this node |
OPCUA.Server.Node.setDataType(handle, "UINT32")
setDataTypeByNode()
Set the type of the OPC UA node. For standard node types use the function setDataType instead. Only applies to nodes of type VARIABLE or VARIABLE_TYPE.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
type |
OBJECT OPCUA.Server.Node |
The OPC UA Node which represents the type |
OPCUA.Server.Node.setDataTypeByNode(handle, typeNode)
setDescription()
Sets the description (explaining text) of the node. Optional. If not called, BrowseName is used.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
description |
STRING |
The description text |
OPCUA.Server.Node.setDescription(handle, "Description of this node.")
setDisplayName()
Sets the name of the node that is used for displaying at clients. Optional. If not called, BrowseName is used.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
displayName |
STRING |
The display name to use |
OPCUA.Server.Node.setDisplayName(handle, "MySimpleVariableNode")
setEnumChoices()
Function to an enum choice to a DATA_TYPE node. Will make the node automatically sub node of Enumeration type (i=29). The same name must not be given multiple times.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
value |
STRING |
Name of the choice to add |
OPCUA.Server.Node.setEnumChoices(handle, {"NAME OF THE CHOICE", "NAME OF CHOICE 2"})
setID()
Sets the ID of the OPC UA node.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
type |
ENUM NodeIDType |
Which type of ID to use |
id |
AUTO |
The ID. Must be unique within a namespace |
OPCUA.Server.Node.setID(handle, "STRING", "MySimpleVariableNode")
setMethodBehavior()
This function is used to register a callback that is executed when a client calls the method. Optionally, it is possible to set one or more return values and parameters for the method.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
callback |
STRING |
Function name to call when client calls the method. Is optional, a callback is not needed if this METHOD node is part of an OBJECT_TYPE. |
returnValues |
ENUM DataType |
Specifies number and data type of the method return values |
parameters |
ENUM DataType |
Specifies number and data type of method parameters |
OPCUA.Server.Node.setMethodBehavior(handle, "callbackFunctionName", {"BOOL"}, {"INT32"}) -- This method takes one INT32 as argument and returns BOOL
setTypeDefinition()
Set the type of the OPC UA node to one of the standard node types. Arbitrary types can be set by using the function setTypeDefinitionByNode instead.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
type |
ENUM NodeType |
The type of this node |
OPCUA.Server.Node.setTypeDefinition(handle, "FOLDER_TYPE")
setTypeDefinitionByNode()
Set the type of the OPC UA node. For standard node types, the function setTypeDefinition can be used instead.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
type |
OBJECT OPCUA.Server.Node |
The OPC UA Node which represents the type |
OPCUA.Server.Node.setTypeDefinitionByNode(handle, typeNode)
setValue()
Sets the current value of the OPC UA node. Only works if NodeClass is VARIABLE or OBJECT.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
value |
AUTO |
The new value for the node |
OPCUA.Server.Node.setValue(handle, 123)
Events
OnWrite
This event is thrown when a Node of type VARIABLE is written by a OPC UA client. It is not thrown when a Node is written internally via API function OPCUA.Server.Node.setValue(). If the write does not change the value, the event is thrown anyway.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Node |
OPCUA.Server.SecurityConfiguration
A security configuration consists of (1) a set of credentials (a certificate and a private key representing the server), (2) a SecurityPolicy, (3) a set of MessageSecurityModes and (4) a set of UserTokenPolicies. Each endpoint has one or more SecurityConfigurations.
Overview
Functions
create()
Creates a SecurityConfiguration with default settings. Default settings are: (1) UserTokenPolicy = ANONYMOUS, (2) MessageSecurityMode = NONE, (3) no server credentials and (4) SecurityPolicy = NONE
| Name | Type | Description |
|---|---|---|
config |
Default SecurityConfiguration instance |
handle = OPCUA.Server.SecurityConfiguration.create()
setMessageSecurityModes()
Sets a set of MessageSecurityModes.
| Name | Type | Description |
|---|---|---|
config |
The configuration instance whose MessageSecurityModes should be set |
|
modes |
ENUM MessageSecurityMode |
Non-empty, duplicate-free list of MessageSecurityModes |
setSecurityPolicy()
Sets the security policy
| Name | Type | Description |
|---|---|---|
config |
The configuration instance whose SecurityPolicy should be set |
|
securityPolicy |
ENUM SecurityPolicy |
The SecurityPolicy to use |
setServerCredentials()
Sets the server credentials. The certificate and the private key have to match. Either specify both or none. Specify none in case that no server credentials should be used (i.e., no signing and/or encryption is used). Parameters certificate and privateKey are interpreted in the context of the used certificate store. When used together with a FileCertificateStoreConfiguration, certificate and privateKey parameters are interpreted as files. However, future releases might introduce different types of key stores (e.g., remote certificate stores or hardware key stores). In that case, parameters certificate and privateKey specify something different than file names.
| Name | Type | Description |
|---|---|---|
config |
The configuration instance whose server credentials should be set |
|
certificate |
STRING |
When using FileCertificateStoreConfiguration, this parameter specifies the name of the file where the certificate to be used for the server is stored in DER format. Use empty string ("") if no certificate shall be used. |
privateKey |
STRING |
When using FileCertificateStoreConfiguration, this parameter specifies the name of the file where the private key to be used for the server is stored in PEM format. Use empty string ("") if no private key shall be used. |
setUserTokenPolicies()
Sets a set of UserTokenPolicies.
| Name | Type | Description |
|---|---|---|
config |
The configuration instance whose UserTokenPolicies should be set |
|
policies |
ENUM UserTokenPolicy |
Non-empty, duplicate-free list of UserTokenPolicies |
OPCUA.Server.ServerConfiguration
Configuration of an OPC UA server. Default server configuration has (1) a list with one EndpointConfiguration set to default values.
Overview
Functions
create()
Creates a server configuration with default parameters.
| Name | Type | Description |
|---|---|---|
config |
The created configuration. |
obj = OPCUA.Server.ServerConfiguration.create()
setEndpointConfigurations()
Sets the endpoint configurations.
| Name | Type | Description |
|---|---|---|
config |
The ServerConfigration whose EndpointConfigurations should be set. |
|
endpointConfigurations |
Non-empty list of EndpointConfigurations. |
OPCUA.Server.UserTokenDatabase
UserTokenDatabase is used for maintaining a set of user credentials that can be used to authenticate at an OPC UA Endpoint. UserTokenDatabases are set to EndpointConfigurations in a reference-like manner. This was done to allow several endpoints to use the same UserTokenDatabase. When endpoints are created from a ServerConfiguration, server starts to uses the references UserTokenDatabase(s). As consequences, any changes to a user database apply directly to the (running) server.
Overview
Functions
addUserPassword()
Add a user with a password to the database.
| Name | Type | Description |
|---|---|---|
database |
The database to add the user to. |
|
userName |
STRING |
Name of the user. |
password |
STRING |
Password of the user |
create()
Creates an empty database.
| Name | Type | Description |
|---|---|---|
database |
The created database. |
obj = OPCUA.UserTokenDatabase.create()
OPCUA.Server.Value
The Value crown allows to create, access and modify OPC UA values as specified in OPC UA specification parts 3, 4 and 6. Values can be (1) used to set or get the value of OPC UA variable or variable type nodes, (2) used as parameters to OPC UA method calls, (3) or used as parameters to OPC UA events. Values can be (1) simple, built-in OPC UA data types (e.g., int16, string, an enumeration value), (2) OPC UA structures containing (optional) named fields, (3) OPC UA unions, (4) or arrays of the aforementioned value types. Fields of a Value are addressed by paths. The empty path "" addresses the current element. All OPC UA built-in data types are accessed through using an empty path. In structures and unions, fields have unique names. They can be addressed by their names. Nested fields are separated by dots ("."). Array members are addressed by zero-based indices in brackets ([]).
Overview
Functions
getActiveUnionField()
Get the field that is currently active at the union
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Value |
path |
STRING |
The path of the member |
| Name | Type | Description |
|---|---|---|
field |
ENUM UnionField |
The field that is currently set active |
OPCUA.Server.Value.getActiveUnionField(handle, "")
getArrayLength()
Get the current element count of an array
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Value |
path |
STRING |
The path of the member to be resized |
| Name | Type | Description |
|---|---|---|
length |
INT |
The current element count of the array or -1 if the selected path is not an array or NULL |
OPCUA.Server.Value.getArrayLength(handle, "")
getOptionalFieldState()
Get the state of an optional structure field
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Value |
path |
STRING |
The path of the member to be enabled/ disable |
| Name | Type | Description |
|---|---|---|
state |
AUTO |
The current state of the field, or nil if field is non-optional. |
OPCUA.Server.Value.getOptionalFieldState(handle, "")
getValue()
Get the builtin value(s) contained in the Value instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Value |
path |
STRING |
The path of the member |
| Name | Type | Description |
|---|---|---|
value |
AUTO |
The builtin value |
local value = OPCUA.Server.Value.getValue(handle, "some_field.an_integer")
resizeArray()
Set the new element count of an array
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Value |
newSize |
INT |
The new element count of the array |
path |
STRING |
The path of the member |
OPCUA.Server.Value.resizeArray(handle, 10, "")
setArrayToNull()
Set an array to NULL. (In OPC UA, array can have length 0 OR be null.)
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Value |
path |
STRING |
The path of the member to be nulled |
OPCUA.Server.Value.setArrayToNull(handle, "")
setOptionalFieldState()
Enable / disable an optional field of a structure
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Value |
state |
ENUM OptionalFieldState |
The new field state |
path |
STRING |
The path of the member to be enabled/ disabled |
OPCUA.Server.Value.setOptionalFieldState(handle, "ENABLED", "")
setValue()
Sets the builtin value of the Value instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Value |
value |
AUTO |
The builtin value |
path |
STRING |
The path of the member |
OPCUA.Server.Value.setValue(handle, 123, "some_field.an_integer")
switchUnionField()
Set the field of a union that is active
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the OPC UA Value |
field |
ENUM UnionField |
The field to be set active |
path |
STRING |
The path of the member to be activated |
OPCUA.Server.Value.switchUnionField(handle, "FIELD_1", "")
Object
Provides functionality to work on object datatypes. Persistence is one of the main features. Currently supported data format: JSON (file extension ".json") and MessagePack (file extension .msgpack)
Overview
Functions
clone()
Creates a full deep copy clone of the provided object/handle. Can fail if the object/handle does not support cloning.
| Name | Type | Description |
|---|---|---|
obj |
CONST_AUTO |
The object/handle to clone |
| Name | Type | Description |
|---|---|---|
cloneObj |
AUTO |
The cloned object/handle. Nil if clone was not possible or not successful. |
deserialize()
De-Serializes an object from a byte array
| Name | Type | Description |
|---|---|---|
serializedData |
BINARY |
The serialized data |
dataFormat |
ENUM DataFormat |
Data format specification |
| Name | Type | Description |
|---|---|---|
obj |
AUTO |
A valid object/handle (or multiple of them) in case of success, no value in case of error |
obj = Object.deserialize(data, "JSON")
getType()
Returns the type name of an object/handle which is the CROWN name assigned to the object
| Name | Type | Description |
|---|---|---|
obj |
CONST_AUTO |
The object/handle to get the type from |
| Name | Type | Description |
|---|---|---|
crownName |
STRING |
The name of the CROWN the object is assigned to |
load()
Loads an object/handle content from a file. When the type parameter is not passed, the data format is guessed from the file extension.
| Name | Type | Description |
|---|---|---|
fileName |
STRING |
The file where the data should read from |
dataFormat |
ENUM DataFormat |
Optional data format specification. If omitted, it is guessed from the file name extension |
| Name | Type | Description |
|---|---|---|
obj |
AUTO |
A valid object/handle (or multiple of them) in case of success, no value in case of error |
object = Object.load("private/FileContent.json")
save()
Saves an object content to a file. If the data type enumeration is not passed as argument, the file extension is used to guess the data format.
| Name | Type | Description |
|---|---|---|
obj |
CONST_AUTO |
The object/handle(s) to be saved. Only objects/handle types are supported. Saving of handles is reserved for future use. |
fileName |
STRING |
The file where the data should be written to |
dataFormat |
ENUM DataFormat |
Optional data format specification. If omitted, it is guessed from the file name extension |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
true when saving succeeded, false when there was an error. In case of errors, please look at the console for error information |
success = Object.save(data, "private/FileContent.json")
serialize()
Serializes an object to a byte array
| Name | Type | Description |
|---|---|---|
obj |
CONST_AUTO |
The object/handle(s) to be serialized. Only objects/handle types are supported. In case of handles, the configuration data is saved which was passed at the creation of the handle (if supported by the handle) |
dataFormat |
ENUM DataFormat |
Data format specification |
| Name | Type | Description |
|---|---|---|
serializedData |
BINARY |
The serialized data in case of success, no data otherwise |
buf = Object.serialize(data, "JSON")
toConst()
Return the provided object explicitly as const object. This is useful to guarantee further const usage of the object. The input object is not touched and stays non-const.
| Name | Type | Description |
|---|---|---|
obj |
CONST_OBJECT [API:DataFormat:] |
The object to return as const |
| Name | Type | Description |
|---|---|---|
constObj |
CONST_OBJECT [API:DataFormat:] |
The same object but as const |
Parameters
Provides access to parameters of the current application and the device parameters. This CROWN implements the AppSpace Parameters component. Read more about Parameters in the AppSpace documentation. Parameters could be basic types (int, bool, …) which can be accessed over "Parameters.get" and "Parameters.set" in this case. Parameters could be complex types (array, struct, …) which can be accessed over "Parameters.getNode" and "Parameters.setNode" in this case. Complex parameters are represented as "Parameters.Node" object and can be accessed and navigated over its functions.
Overview
Functions
apply()
Parameters of the device are not automatically activated when calling the Parameters.set/setNode function. This function has to be called after using the "Parameters.set" or "Parameters.setNode" function so that they are applied on the device. Please note that the parameters are not directly updated if this function returns. The event "Parameters.OnParametersChanged" is triggered after calling this function when the parameters are updated to inform the device and other applications.
Parameters.apply()
get()
Returns the value of the specified parameter. Please note that all parameter repositories of the device are considered, not only application parameters. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If read fails function returns nothing. It can fail if the parameter is not existing or it has a complex type. If it has a complex type please use the "Parameters.getNode" function.
| Name | Type | Description |
|---|---|---|
varName |
STRING |
The name or path of the parameter to be read |
| Name | Type | Description |
|---|---|---|
varValue |
AUTO |
The value(s) of the parameter. Nil if parameter does not exist or type not possible. The type which is returned depends on the value of the parameter. |
-- Usage possibilities:
local theParam = Parameters.get("LocationName") -- single string parameter get
local subValue = Parameters.get("MyParameter/subValue") -- get over xpath
local arrayValue = Parameters.get("MyArray[0]") -- get first array value
getNode()
Returns a copy of the parameter as "Parameters.Node" to navigate in the parameter structure. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The return object is a copy of the current parameter values. If it is changed, the "Parameters.setNode" function has to be called with the object.
| Name | Type | Description |
|---|---|---|
varName |
STRING |
The name or path of the parameter to be written |
| Name | Type | Description |
|---|---|---|
nodeObjectCopy |
OBJECT Parameters.Node |
The copy of the node object of the parameter or nil if parameter does not exist |
-- Get a parameter node, get all member nodes of it and print how much nodes the parameter has:
local theNode = Parameters.getNode("MyComplexParameter")
local subNodes = Parameters.Node.getNode(theNode)
print("Number of subnodes in MyComplexParameter: " .. ##subNodes)
loadAllDefaults()
Loads the default values of all parameters of the device. It affects all parameters of all apps as well as the parameters of the device. Concretely this function sets all parameters to factory defaults. This function does NOT do a save permanent.
Parameters.loadAllDefaults()
loadBlockDefaults()
Loads the default values of all app parameters in the specified block of all loaded parameter files. This function does NOT work with device parameters, only with app parameters.
| Name | Type | Description |
|---|---|---|
blockName |
STRING |
The name of the block in the app parameters file(s) |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully restored the default values for the block(s). False on error or block does not exist in no parameters file |
loadDefault()
Loads the default value of the specified app parameter. This function does NOT work with device parameters, only with app parameters.
| Name | Type | Description |
|---|---|---|
varName |
STRING |
The name or path of the parameter to be load the default value |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully restored the default value- False on error or block does not exist |
Parameters.loadDefault("MyParameter")
loadPermanent()
This function restores all current permanent stored values of all application and device parameters. Per default a permanent load is done automatically on bootup of the device. This function blocks until the restoring is done. There is no apply on the parameters done and no OnParametersChanged event thrown. The user has to call the apply() function manually.
Parameters.loadPermanent()
savePermanent()
This function stores the current parameter values of all applications and the device permanently. The values of the permanent stored parameters are automatically loaded on bootup of the device again. This function blocks until the storing is done.
Parameters.savePermanent()
set()
Sets the value of the specified parameter. Please note that all parameter repositories of the device are considered, not only application parameters. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If set fails the function returns false. Parameter values are directly updated and CoLa events are directly fired (also if the values are identical), but device parameters are not directly activated. Therefore if device parameters have been changed, the "Parameters.apply" function needs to be called so that they get active.
| Name | Type | Description |
|---|---|---|
varName |
STRING |
The name or path of the parameter to be written |
varValue |
AUTO |
The value(s) of the parameter. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully set. False if parameter does not exist or type does not match the parameter declaration |
-- Usage possibilities:
local bSuccess = Parameters.set("LocationName", "Mydevice") -- set single string parameter value
local bSuccess = Parameters.set("MyParameter/memberString", "stringValue") -- set sub parameter value
local bSuccess = Parameters.set("MyArray[0]", 123) -- set first array value
setNode()
Sets the value of the specified parameters as "Parameters.Node". This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The specified node content and structure has to match the parameter declaration. A matching node for a parameter can be get over "Parameters.getNode". If set fails the function returns false. Parameter values are directly updated and CoLa events are directly fired (also if the values are identical), but device parameters are not directly activated. Therefore if device parameters have been changed, the "Parameters.apply" function needs to be called so that they get active.
| Name | Type | Description |
|---|---|---|
varName |
STRING |
The name or path of the parameter to be written |
nodeObject |
CONST_OBJECT Parameters.Node |
The node object with the new values. The node structure has to match the parameter |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully set. False if parameter does not exist or node structure does not match the parameter declaration |
-- Get a parameter node, modify it and write the whole parameter:
local theNode = Parameters.getNode("MyComplexParameter")
Parameters.Node.set(theNode, "memberString", "stringValue")
Parameters.setNode("MyComplexParameter", theNode)
Events
OnAllDefaultsLoaded
This event is notified when the all parameter default values were loaded. A all-defaults-loading can be triggered by the API function "Parameters.loadAllDefaults" and over the command interface.
OnParametersChanged
This event is notified when the parameters of the application or the device might have changed. There is no information if parameters are really changed or which parameters are changed. This event might also be thrown even when were no parameters changed at all. The user has to read its parameters using the "Parameters.get" function and detect himself if it has changed.
OnParametersLoaded
This event is notified when the parameters were restored from permanent storage. A load permanent is triggered by the API function "Parameters.loadPermanent" or over the command interface.
OnParametersSaved
This event is notified when the parameters were stored permanently. A save permanent is triggered by the API function "Parameters.savePermanent" or over the command interface.
Parameters.Listener
Provides functionality to register for or poll changes of parameter values. One listener could listen to several parameters by using the add()-function multiple times. The user could register for an OnChanged-event to get every write to a listened parameter. Alternatively it could only use isChanged()- and clearChanged()-functions and e.g. call them during 'Engine.OnStarted' event handling. This functionality does NOT work with device parameters, only with app parameters.
Functions
add()
Adds a parameter name to listen to
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of Parameters.Listener |
paramName |
STRING |
The name of the parameter to listen to |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully added. False if not possible or parameter does not exist |
Parameters.Listener.add(handle, "MyParameterName")
clearChanged()
Clears a changed state manually.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of Parameters.Listener |
Parameters.Listener.clearChanged(handle)
create()
Creates a new listener instance. The listener stays active as long as this instance exists.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The new Parameters.Listener instance |
handle = Parameters.Listener.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
isChanged()
Polls the current changed state. State needs to be reset manually using the clearChanged()-function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of Parameters.Listener |
| Name | Type | Description |
|---|---|---|
changed |
BOOL |
True if the parameters was |
local bIsChanged = Parameters.Listener.isChanged(handle)
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
Events
OnChanged
Is thrown if the value of the parameters has changed or is written with same value
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of Parameters.Listener |
Parameters.Listener.register(handle, "OnChanged", "handleChanged")
Parameters.Node
A "Parameters.Node" object represents a parameter composition or one leaf of it. If can be used to navigate in the tree of the complex parameter to access or modify values. A node cannot be created by this CROWN, but it is returned e.g. from "Parameters.getNode".
Overview
Functions
get()
Gets the single value or all values of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If the accessed leaf is a struct or array, then use the getNode()-function instead.
| Name | Type | Description |
|---|---|---|
nodeObject |
CONST_OBJECT Parameters.Node |
The instance of the object to use |
relativePath |
STRING |
The name or relativePath to access. Nil if accessing this node |
| Name | Type | Description |
|---|---|---|
varValue |
AUTO |
The value(s) of the parameter. Nil if parameter does not exist or type not possible. The type which is returned depends on the value of the parameter. |
-- Usage possibilities:
local singleValue = Parameters.Node.get(node) -- if the node is a single value get it
local singleSubValue = Parameters.Node.get(node, "subValue") -- get the member value "subValue" of this node if it is a struct
local arraySubValue = Parameters.Node.get(node, "subArray") -- get all the member array values of member "subArray" if it is a struct
local arrayValue = Parameters.Node.get(node, "[0]") -- get the first index value of an array node. Index number is interpreted as hex-number.
local singleSubArrayValue = Parameters.Node.get(node, "subMember/subArray[0]") -- get the first value of the subArray which is member of the subMember struct. Index number is interpreted as hex-number.
getAllNodes()
Gets copies of all children nodes of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. It is possible to get the children of structs and arrays.
| Name | Type | Description |
|---|---|---|
nodeObject |
CONST_OBJECT Parameters.Node |
The instance of the object to use |
relativePath |
STRING |
The name or relativePath to access. Nil if accessing this node |
| Name | Type | Description |
|---|---|---|
nodeObjectCopies |
OBJECT Parameters.Node |
The copies of the node objects of the parameter or nil if parameter does not exist |
-- Usage possibilities:
local subNodes = Parameters.Node.getAllNodes(node) -- get all sub nodes of the node
local subNodes = Parameters.Node.getAllNodes(node, "subMember") -- get all member nodes of a sub struct
getArraySize()
Returns the size if this node is an array. If it is a flexible array, then the current size is returned.
| Name | Type | Description |
|---|---|---|
nodeObject |
CONST_OBJECT Parameters.Node |
The instance of the object to use |
relativePath |
STRING |
The name or relativePath to access. Nil if accessing this node |
| Name | Type | Description |
|---|---|---|
size |
INT |
The current size of the array. Nil if it is not an array |
local arrSize = Parameters.Node.getArraySize(node)
getNode()
Gets a copy of a single node of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers.
| Name | Type | Description |
|---|---|---|
nodeObject |
CONST_OBJECT Parameters.Node |
The instance of the object to use |
relativePath |
STRING |
The name or relativePath to access. Nil if accessing this node |
| Name | Type | Description |
|---|---|---|
nodeObjectCopy |
OBJECT Parameters.Node |
The copy of the node object of the parameter or nil if parameter does not exist |
-- Usage possibilities:
local subNode = Parameters.Node.getNode(node, "childName") -- get one member node named "childName"
local subArraynode = Parameters.Node.getNode(node, "subMember/subArray[0]") -- get the first value of the subArray which is member of subMember struct. Index number is interpreted as hex-number.
set()
Sets the single value or all values of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. If set fails the function returns false.
| Name | Type | Description |
|---|---|---|
nodeObject |
OBJECT Parameters.Node |
The instance of the object to use |
varValue |
AUTO |
The value(s) of the parameter. Nil if parameter does not exist or type not possible. The type has to match the declaration of the parameter. |
relativePath |
STRING |
The name or relativePath to access. Nil if accessing this node |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully set. False if parameter does not exist or type does not match the parameter declaration |
-- Usage possibilities:
local bSuccess = Parameters.Node.set(node, "stringValue") -- Set a single value to this node if it is a string parameter node
local bSuccess = Parameters.Node.set(node, "stringValue", "memberString") -- Set a value to one member of this node if it is a struct
setAllNodes()
Sets all specified nodes as children to this node or to a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The specified node content and structure has to match the current node parameter declaration. It is possible to set the children of structs and arrays. If set fails the function returns false. This node can be inconsistent in case of fail.
| Name | Type | Description |
|---|---|---|
nodeObject |
OBJECT Parameters.Node |
The instance of the object to use |
valueObject |
CONST_OBJECT Parameters.Node |
The node objects with the new values. The node structure has to match the parameter. Values are copied to the nodeObject. |
relativePath |
STRING |
The name or relativePath to access. Nil if accessing this node |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully set. False if parameter does not exist or node structure does not match the parameter declaration |
-- Usage possibilities:
local bSuccess = Parameters.Node.setAllNodes(node, nodeVector) -- set the nodes of the vector to this one
setArraySize()
Sets the size of this node if it is an array and the size or the array is declared as flexible
| Name | Type | Description |
|---|---|---|
nodeObject |
OBJECT Parameters.Node |
The instance of the object to use |
size |
INT |
The new size of the array |
relativePath |
STRING |
The name or relativePath to access. Nil if accessing this node |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successful set. False if array size does not match the parameter declaration. |
Parameters.Node.setArraySize(node, 5)
setNode()
Sets the single node of this node or of a child node addressed by a relativePath. This function can also access just one leaf of a complex parameter by addressing over xPath syntax. The numbers used for array access are interpreted as hex-numbers. The specified node content and structure has to match the current node parameter declaration. If set fails the function returns false.
| Name | Type | Description |
|---|---|---|
nodeObject |
OBJECT Parameters.Node |
The instance of the object to use |
valueObject |
CONST_OBJECT Parameters.Node |
The node object with the new values. The node structure has to match the parameter. Values are copied to the nodeObject. |
relativePath |
STRING |
The name or relativePath to access. Nil if accessing this node |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully set. False if parameter does not exist or node structure does not match the parameter declaration |
-- Usage possibilities:
local bSuccess = Parameters.Node.setNode(node, otherNode) -- sets the values of another node to this one
Parameters.Validator
Provides functionality to hook in to parameter writes to decide if a write is allowed or not. One validator could validate several parameters by using the add()-function multiple times. The validator function can be set using the setCallback()-function. See description of the setCallback()-function for details about the callback implementation. This functionality does NOT work with device parameters, only with app parameters.
Overview
Functions
add()
Adds a parameter name to validate
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of Parameters.Validator |
paramName |
STRING |
The name of the parameter to validate |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully added. False if not possible or parameter does not exist |
Parameters.Validator.add(handle, "MyParameterName")
create()
Creates a new validator instance. The validator stays active as long as this instance exists.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The new Parameters.Validator instance |
handle = Parameters.Validator.create()
handle:add("MyParam")
function callback(paramName, paramNode)
-- Use paramName and paramNode to decide if return true/false
return bOk
end
handle:setCallback(handle, callback)
setCallback()
Sets the validator callback function which is called upon writes to the added parameters. The function gets called with two parameters: The parameter name and a Parameters.Node const-object containing the value which wants to be written. It is not guaranteed that the second parameter with the value object is available. If the parameter write is done over communication interfaces, it is present, but if the write is done using Parameters.set()-function, it is not available. The function gets called in blocking mode and the current parameter-write is blocked until the function returns. If the function returns true, the parameter-write is done. If false, then there is an error thrown on the CoLa command interface with number 0x4 (condition wrong)
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of Parameters.Validator |
funcCallback |
STRING |
The function name to be called for validation. Needs to have a specific signature, read more about in the function documentation. |
function callback(paramName, paramNode)
-- get values from "paramNode" using Parameters.Node-functions
-- if writing should be done, return true. Otherwise return false.
return bOk
end
Parameters.Validator.setCallback(handle, callback)
Point
Represents a point/vector in 2D or 3D
Overview
add(), addConstant(), clone(), create(), cross(), divide(), divideConstant(), dot(), getDistance(), getDistanceToLine(), getDistanceToPlane(), getX(), getXY(), getXYZ(), getY(), getZ(), is2D(), is3D(), isFinite(), isZero(), multiply(), multiplyConstant(), negate(), norm(), normalize(), projectOntoPlane(), setX(), setXY(), setXYZ(), setY(), setZ(), subtract(), subtractConstant(), toMatrix(), toString(), transform()
Functions
add()
Add the corresponding components of two points.
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
Input point 1 |
point2 |
CONST_OBJECT Point |
Input point 2 |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
Output point |
pointOut = Point.add(point1, point2)
addConstant()
Add a constant to each component.
| Name | Type | Description |
|---|---|---|
pointIn |
CONST_OBJECT Point |
Input point |
constant |
FLOAT |
The constant |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
Output point |
pointOut = Point.addConstant(pointIn, constant)
clone()
Create a copy of a point.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
clonedPoint |
OBJECT Point |
Copy of the input point |
clonedPoint = Point.clone(point)
create()
Create 2D or 3D point(s). The third z-coordinate input is optional, if omitted a 2D point is created, otherwise a 3D point. Vector input is allowed to create vectors of points. The input vectors must then all be of equal length. The following input combinations are allowed: Two scalar floats give a 2D point (x,y) Three scalar floats give a 3D point (x,y,z) Two vectors of equal length give a vector of 2D points Three vectors of equal length give a vector of 3D points
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
X coordinate, a scalar or vector. |
y |
FLOAT |
Y coordinate, a scalar or vector. |
z |
FLOAT |
Z coordinate, a scalar or vector. Optional: if omitted, 2D points will be created. |
| Name | Type | Description |
|---|---|---|
point |
OBJECT Point |
The created point or vector of points. |
point = Point.create({1.0, 2.0}, {3.0, 4.0})
cross()
Calculates the cross product of two point vectors (only 3D). The cross product is anti-commutative: a x b = -(b x a)
| Name | Type | Description |
|---|---|---|
a |
CONST_OBJECT Point |
Input point |
b |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
product |
OBJECT Point |
The cross product |
product = Point.cross(a, b)
divide()
Divide the components of the first point with the corresponding components of the second point.
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
Input point 1 |
point2 |
CONST_OBJECT Point |
Input point 2 |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
Output point |
pointOut = Point.divide(point1, point2)
divideConstant()
Divide each component with a constant.
| Name | Type | Description |
|---|---|---|
pointIn |
CONST_OBJECT Point |
Input point |
constant |
FLOAT |
The constant |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
Output point |
pointOut = Point.divideConstant(pointIn, constant)
dot()
Calculates the dot product of two point vectors of the same dimensionality (e.g. x1*x2+y1*y2+z1*z2).
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
Input point |
point2 |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
product |
FLOAT |
The dot product |
product = Point.dot(point1, point2)
getDistance()
Compute the distance between the two points of the same dimensionality (2D or 3D).
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
Input point |
point2 |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
distance |
FLOAT |
Distance between the points |
distance = Point.getDistance(point1,point2)
getDistanceToLine()
Calculates the distance from a point to a line (2D/3D).
| Name | Type | Description |
|---|---|---|
pointIn |
CONST_OBJECT Point |
Input point |
line |
CONST_AUTO |
Input line (Shape/Shape3D). |
| Name | Type | Description |
|---|---|---|
distance |
FLOAT |
The distance from point to line or nil for invalid input combination |
local distance = Point.getDistanceToLine(pointIn, line)
getDistanceToPlane()
Calculates the distance from a point to a plane (only 3D).
| Name | Type | Description |
|---|---|---|
pointIn |
CONST_OBJECT Point |
Input point |
plane |
CONST_OBJECT Shape3D |
Input plane. |
| Name | Type | Description |
|---|---|---|
distance |
FLOAT |
The distance from point to plane |
local distance = Point.getDistanceToPlane(pointIn, plane)
getX()
Get the X coordinate of a point.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
x coordinate of the point |
x = Point.getX(point)
getXY()
Get the X and Y coordinates of a point.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
x coordinate of the point |
y |
FLOAT |
y coordinate of the point |
x,y = Point.getXY(point)
getXYZ()
Get the X, Y and Z coordinates of a point (only 3D).
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
x coordinate of the point |
y |
FLOAT |
y coordinate of the point |
z |
FLOAT |
z coordinate of the point |
x,y,z = Point.getXYZ(point)
getY()
Get the Y coordinate of a point.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
y |
FLOAT |
y coordinate of the point |
y = Point.getY(point)
getZ()
Get the Z coordinate of a point (only 3D).
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
z |
FLOAT |
z coordinate of the point |
z = Point.getZ(point)
is2D()
Check if a point is a 2D point.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
ret |
BOOL |
True if 2D point, otherwise false |
ret = Point.is2D(point)
is3D()
Check if a point is a 3D point.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
ret |
BOOL |
True if 3D point, otherwise false |
ret = Point.is3D(point)
isFinite()
Check if a point is finite, i.e. none of the values is Inf/NaN.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
ret |
BOOL |
True if finite point, otherwise false |
ret = Point.isFinite(point)
isZero()
Returns true if all coordinates are zero.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
ret |
BOOL |
True if all coordinates are zero, otherwise false |
ret = Point.isZero(point)
multiply()
Multiply the corresponding components of two points.
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
Input point 1 |
point2 |
CONST_OBJECT Point |
Input point 2 |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
Output point |
pointOut = Point.multiply(point1, point2)
multiplyConstant()
Multiply each component with a constant.
| Name | Type | Description |
|---|---|---|
pointIn |
CONST_OBJECT Point |
Input point |
constant |
FLOAT |
The constant |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
Output point |
pointOut = Point.multiplyConstant(pointIn, constant)
negate()
Returns the negated point vector (every component changes its sign).
| Name | Type | Description |
|---|---|---|
pointIn |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
The negated point |
pointOut = Point.negate(pointIn)
norm()
Calculates different types of non-negative vector norms. If no enumeration is provided, the "L-2-Norm" will be calculated, which represents the magnitude or length of the point vector.
| Name | Type | Description |
|---|---|---|
pointIn |
CONST_OBJECT Point |
Input point |
type |
ENUM NormType |
Norm type enumeration |
| Name | Type | Description |
|---|---|---|
norm |
FLOAT |
The norm |
norm = Point.norm(pointIn)
normalize()
Returns the unit vector (length=1) with the same direction or nil if the input point vector has the length 0.
| Name | Type | Description |
|---|---|---|
pointIn |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
The normalized point vector or nil |
pointOut = Point.normalize(pointIn)
projectOntoPlane()
Projects one or multiple points onto a plane (only 3D).
| Name | Type | Description |
|---|---|---|
pointIn |
CONST_OBJECT Point |
Input point(s) |
plane |
CONST_OBJECT Shape3D |
The projection plane. |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
The point(s) on the plane |
pointOut = Point.projectOntoPlane(pointIn, plane)
setX()
Set the X coordinate of a point.
| Name | Type | Description |
|---|---|---|
point |
OBJECT Point |
Input point |
x |
FLOAT |
X coordinate |
Point.setX(point, x)
setXY()
Set the X and Y coordinates of a point.
| Name | Type | Description |
|---|---|---|
point |
OBJECT Point |
Input point |
x |
FLOAT |
X coordinate |
y |
FLOAT |
Y coordinate |
Point.setXY(point, x, y)
setXYZ()
Set the X, Y and Z coordinates of a point (only 3D).
| Name | Type | Description |
|---|---|---|
point |
OBJECT Point |
Input point |
x |
FLOAT |
X coordinate |
y |
FLOAT |
Y coordinate |
z |
FLOAT |
Z coordinate |
Point.setXYZ(point, x, y, z)
setY()
Set the Y coordinate of a point.
| Name | Type | Description |
|---|---|---|
point |
OBJECT Point |
Input point |
y |
FLOAT |
Y coordinate |
Point.setY(point, y)
setZ()
Set the Z coordinate of a point (only 3D).
| Name | Type | Description |
|---|---|---|
point |
OBJECT Point |
Input point |
z |
FLOAT |
Z coordinate |
Point.setZ(point, z)
subtract()
Subtract the corresponding components of the second point from those of the first point.
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
Input point 1 |
point2 |
CONST_OBJECT Point |
Input point 2 |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
Output point |
pointOut = Point.subtract(point1, point2)
subtractConstant()
Subtract a constant from each component.
| Name | Type | Description |
|---|---|---|
pointIn |
CONST_OBJECT Point |
Input point |
constant |
FLOAT |
The constant |
| Name | Type | Description |
|---|---|---|
pointOut |
OBJECT Point |
Output point |
pointOut = Point.subtractConstant(pointIn, constant)
toMatrix()
Converts a point or a vector of points to a matrix.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point, or vector of points to convert to a matrix. |
storeInColumns |
BOOL |
When true the points are placed in the columns of the matrix, when false in the rows of the matrix. |
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
Matrix created from the points. |
matrix = Point.toMatrix(point, storeInColumns)
toString()
Get a string representation of the point.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point |
| Name | Type | Description |
|---|---|---|
str |
STRING |
String representation of the point |
print("The point is: " .. Point.toString(point))
transform()
Transforms point or a vector of points. For 2D points a 2D transform must be supplied, for 3D points a 3D transform.
| Name | Type | Description |
|---|---|---|
point |
CONST_OBJECT Point |
Input point, or vector of points. |
transform |
CONST_OBJECT Transform |
Transform to apply. |
| Name | Type | Description |
|---|---|---|
transformedPoint |
OBJECT Point |
Transformed point(s). |
transformedPoint = Point.transform(point, transform)
PointCloud
Iconic object for points in a 3D Cartesian coordinate system.
Overview
appendPoint(), clone(), create(), createFromPoints(), createFromVector(), extractIndices(), getBoundingBox(), getBounds(), getCentroid(), getColor(), getColorMode(), getIntensity(), getPoint(), getPoint3D(), getPoints(), getSize(), isDense(), isOrganized(), load(), merge(), mergeInplace(), resample(), save(), setColor(), setIntensity(), setPoint(), toImage(), toImageInplace(), toPoints(), toString(), toVector(), transform(), transformInplace()
Functions
appendPoint()
Appends a new point to the specified point cloud.
| Name | Type | Description |
|---|---|---|
inputCloud |
OBJECT PointCloud |
Point cloud to append the point to |
x |
FLOAT |
X value in [mm] |
y |
FLOAT |
Y value in [mm] |
z |
FLOAT |
Z value in [mm] |
intensity |
FLOAT |
Intensity value |
PointCloud.appendPoint(inputCloud, x, y, z, intensity)
clone()
Returns a duplicated instance of the input cloud. This is a full copy and might be very slow dependent on the cloud size.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The cloud to clone |
| Name | Type | Description |
|---|---|---|
clone |
OBJECT PointCloud |
The new cloned cloud object |
local clone = PointCloud.clone(inputCloud)
create()
Creates a new empty point cloud object
| Name | Type | Description |
|---|---|---|
colorMode |
ENUM ColorMode |
The color mode of this point cloud. Defaults to "INTENSITY". |
| Name | Type | Description |
|---|---|---|
newCloud |
OBJECT PointCloud |
The newly created cloud |
local newCloud = PointCloud.create()
createFromPoints()
Creates a point cloud from a vector of Point objects containing the Cartesian coordinates and an optional intensity value or vector of intensity values. If the input points are only 2D, the z-coordinate of all points in the point cloud is set to 0.
| Name | Type | Description |
|---|---|---|
points |
CONST_OBJECT Point |
Vector of Point objects containing the coordinates. |
intensity |
FLOAT |
Select an intensity between 0 and 1 for the points in the point cloud. Input can be either a single value or one value per point. Default is 1.0. |
| Name | Type | Description |
|---|---|---|
pointcloud |
OBJECT PointCloud |
The resulting point cloud. |
local pointcloud = PointCloud.createFromPoints(points, intensity)
createFromVector()
Creates a point cloud from vectors of x, y, z and intensity values.
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
X values in [mm] |
y |
FLOAT |
Y values in [mm] |
z |
FLOAT |
Z values in [mm] |
intensity |
FLOAT |
Intensity values |
| Name | Type | Description |
|---|---|---|
pointcloud |
OBJECT PointCloud |
The resulting point cloud. |
local pointcloud = PointCloud.createFromVector(x, y, z, intensity)
extractIndices()
Extract a number of points referenced by indices from a point cloud.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The input point cloud. |
indices |
INT |
Indices of the points which will be copied to the output cloud. |
negative |
BOOL |
Set to true to invert the filter behavior (copy all points not in the indices vector), default is false. |
| Name | Type | Description |
|---|---|---|
outputCloud |
OBJECT PointCloud |
The extracted point cloud or nil, if the input point cloud is empty. |
local outputCloud = PointCloud.extractIndices(inputCloud, indices, negative)
getBoundingBox()
Compute the axis-aligned bounding box of all points in this cloud and return a Shape3D object.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The input point cloud. |
| Name | Type | Description |
|---|---|---|
box |
OBJECT Shape3D |
The bounding box or nil, if the input point cloud is empty. |
local box = PointCloud.getBoundingBox(inputCloud)
getBounds()
Compute the axis-aligned bounding box of all points in this cloud and return the float values.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The input point cloud |
| Name | Type | Description |
|---|---|---|
minX |
FLOAT |
X-value of minimum point [mm] |
minY |
FLOAT |
Y-value of minimum point [mm] |
minZ |
FLOAT |
Z-value of minimum point [mm] |
maxX |
FLOAT |
X-value of maximum point [mm] |
maxY |
FLOAT |
Y-value of maximum point [mm] |
maxZ |
FLOAT |
Z-value of maximum point [mm] |
local minX, minY, minZ, maxX, maxY, maxZ = PointCloud.getBounds(inputCloud)
getCentroid()
Compute the centroid (or geometric center) as the arithmetic mean position of all points in this cloud.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The input point cloud. |
| Name | Type | Description |
|---|---|---|
centroid |
OBJECT Point |
The centroid or nil, if the input point cloud is empty. |
local centroid = PointCloud.getCentroid(inputCloud)
getColor()
Get the RGBA color values of the specified points in the point cloud. Works only if the point cloud’s color mode is "RGBA".
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The input point cloud |
indices |
INT |
Indices of the points to get the color from |
| Name | Type | Description |
|---|---|---|
red |
INT |
Red color component (single value or vector of same length as indices) or nil |
green |
INT |
Green color component (single value or vector of same length as indices) or nil |
blue |
INT |
Blue color component (single value or vector of same length as indices) or nil |
alpha |
INT |
Alpha/opacity component (single value or vector of same length as indices) or nil |
local red, green, blue, alpha = PointCloud.getColor(inputCloud, indices)
getColorMode()
Returns the color mode of the point cloud.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The input point cloud |
| Name | Type | Description |
|---|---|---|
colorMode |
ENUM ColorMode |
The color mode of this cloud |
local colorMode = PointCloud.getColorMode(inputCloud)
getIntensity()
Get the intensity value of the specified points in the point cloud. Works only if the point cloud’s color mode is "INTENSITY".
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The input point cloud |
indices |
INT |
Indices of the points to get the intensity from |
| Name | Type | Description |
|---|---|---|
intensity |
FLOAT |
Intensity (single value or vector of same length as indices) or nil |
local intensity = PointCloud.getIntensity(inputCloud, indices)
getPoint()
Returns the x, y, z and intensity value of the specified point in the point cloud as single float values.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The point cloud to get the point from |
index |
INT |
Point index starting from 0 |
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
X value in [mm] |
y |
FLOAT |
Y value in [mm] |
z |
FLOAT |
Z value in [mm] |
intensity |
FLOAT |
Intensity value |
local x,y,z,intensity = PointCloud.getPoint(inputCloud, index)
getPoint3D()
Returns the 3D coordinates of the specified point in the point cloud as Point object and the intensity as float value.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The point cloud to get the point from |
index |
INT |
Optional point index starting from 0 |
| Name | Type | Description |
|---|---|---|
point |
OBJECT Point |
The 3D coordinates as Point object. |
intensity |
FLOAT |
Intensity value |
local point, intensity = PointCloud.getPoint3D(inputCloud, index)
getPoints()
Returns the x, y, z and intensity value of all points in the point cloud as vectors of float values. This function is deprecated, please use PointCloud.toVector instead.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
Point cloud to get the points from |
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
X values in [mm] |
y |
FLOAT |
Y values in [mm] |
z |
FLOAT |
Z values in [mm] |
intensity |
FLOAT |
Intensity values |
local x,y,z,intensity = PointCloud.getPoints(inputCloud)
getSize()
Returns the dimensions of the point cloud.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The point cloud to get the size from |
| Name | Type | Description |
|---|---|---|
size |
INT |
The number of points in this cloud |
width |
INT |
The width of the cloud if organized, total size if not |
height |
INT |
The height of the cloud if organized, 1 if not |
local size,width,height = PointCloud.getSize(inputCloud)
isDense()
Returns true if all the points in this point cloud have valid coordinates (i.e. not Inf/NaN). Clouds provided by a sensor may contain invalid points. This is typically used to ignore points with low confidence and at the same time keep the organized matrix structure of the cloud.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The point cloud to get the attribute from |
| Name | Type | Description |
|---|---|---|
isDense |
BOOL |
True if all the points in this point cloud have valid coordinates |
local isDense = PointCloud.isDense(inputCloud)
isOrganized()
Returns true if the points in this point cloud are organized in rows and columns (i.e. height > 1). This is typically the case when the data has been created by a matrix sensor, e.g. in a time-of-flight camera.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The point cloud to get the attribute from |
| Name | Type | Description |
|---|---|---|
isOrganized |
BOOL |
True if the points in this point cloud are organized in rows and columns |
local isOrganized = PointCloud.isOrganized(inputCloud)
load()
Load a point cloud from the specified file path. The format is defined by the file extension: .ply: Polygon File Format ("ascii" mode only) .pcd: Point Cloud Data File Format ("ascii", "binary" or "binary_compressed" mode) .ssr: SICK Sensor Record .json: JSON .msgpack: MessagePack
| Name | Type | Description |
|---|---|---|
filepath |
STRING |
The path and name of the file to load the point cloud from. |
| Name | Type | Description |
|---|---|---|
loadedCloud |
OBJECT PointCloud |
The PointCloud object which is loaded. |
local loadedCloud = PointCloud.load("resources/cloud.pcd")
merge()
Merge two point clouds by creating a new cloud and appending the points of both clouds to it. The color mode of both point clouds must be identical.
| Name | Type | Description |
|---|---|---|
inputCloud1 |
CONST_OBJECT PointCloud |
The first point cloud. |
inputCloud2 |
CONST_OBJECT PointCloud |
The second point cloud. |
| Name | Type | Description |
|---|---|---|
mergedCloud |
OBJECT PointCloud |
The merged point cloud. |
local mergedCloud = PointCloud.merge(inputCloud1, inputCloud2)
mergeInplace()
In-place version of the PointCloud.merge function that modifies the input point cloud. See base function for full documentation. The color mode of both point clouds must be identical.
| Name | Type | Description |
|---|---|---|
inputCloud1 |
OBJECT PointCloud |
The first point cloud. This point cloud is overwritten with the merged point cloud. |
inputCloud2 |
CONST_OBJECT PointCloud |
The second point cloud. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT PointCloud |
Reference to the result point cloud. |
local result = PointCloud.mergeInplace(inputCloud1, inputCloud2)
resample()
Resample a point cloud using a 3D voxel grid. All points in one voxel are merged to their centroid by averaging their x, y, z and intensity values. It’s possible to specify a minimum number of points inside a voxel to ignore scattered points.
Data Reduction
PointCloud.resample creates an axis-aligned bounding box around the cloud which is subdivided into voxels (volumetric pixels) whose size can be defined with the voxelSizeX/Y/Z parameters.
-
All the points in one voxel of the grid are approximated with their centroid.
-
It’s possible to specify a minimum number of points inside a voxel to ignore scattered points.
Example: The four green points inside this voxel are replaced with their centroid (red point) in the output cloud.
PointCloud.sample chooses a number of random sample points with a uniform probability.
-
It’s a bit faster than resample and preserves the relative density of the cloud.
Input cloud with 50.000 points
PointCloud.sample(4000) - sample 4000 points
PointCloud.resample(5, 5, 5) - 5x5x5 mm voxel
PointCloud.resample(5, 5, 5, 10) - min. 10 points per voxel
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The input point cloud. |
voxelSizeX |
FLOAT |
Voxel size in x-direction. |
voxelSizeY |
FLOAT |
Voxel size in y-direction (uses voxelSizeX if not set). |
voxelSizeZ |
FLOAT |
Voxel size in z-direction (uses voxelSizeX if not set). |
minNumPoints |
INT |
Minimum number of points inside a voxel for creating a point in the output cloud, default is 1. |
| Name | Type | Description |
|---|---|---|
resampledCloud |
OBJECT PointCloud |
The resampled point cloud. |
local resampledCloud = PointCloud.resample(inputCloud, 5.0, 5.0, 5.0, 10)
save()
Save a point cloud to the specified file path. Overwrites the file if it already exists. The format is defined by the file extension: .ply: Polygon File Format ("ascii" mode only) .pcd: Point Cloud Data File Format ("ascii" or "binary" mode) .ssr: SICK Sensor Record .json: JSON (Optional useBinaryPCD parameter not supported). .msgpack: MessagePack (Optional useBinaryPCD parameter not supported).
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The PointCloud object which is saved. |
filepath |
STRING |
The path and name of the file to save the point cloud to. |
useBinaryPCD |
BOOL |
Only applies for .pcd file format. If true write coordinates in binary mode instead of ASCII. Default is false. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if the point cloud has been successfully saved. |
local success = PointCloud.save(inputCloud, "private/cloud.pcd")
setColor()
Set the RGBA color values of the specified points in the point cloud. Works only if the point cloud’s color mode is "RGBA".
| Name | Type | Description |
|---|---|---|
inputCloud |
OBJECT PointCloud |
The input point cloud |
indices |
INT |
Indices of the points to set the color for |
red |
INT |
Red color component in range [0-255]. Must be either a single value or vector of same length as indices. |
green |
INT |
Green color component in range [0-255]. Must be either a single value or vector of same length as indices. |
blue |
INT |
Blue color component in range [0-255]. Must be either a single value or vector of same length as indices. |
alpha |
INT |
Alpha/opacity component in range [0-255] (optional). Must be either a single value or vector of same length as indices or empty. Defaults to 255. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true on success. |
PointCloud.setColor(inputCloud, indices, red, green, blue)
setIntensity()
Set the intensity value of the specified points in the point cloud. Works only if the point cloud’s color mode is "INTENSITY".
| Name | Type | Description |
|---|---|---|
inputCloud |
OBJECT PointCloud |
The input point cloud |
indices |
INT |
Indices of the points to set the intensity for |
intensity |
FLOAT |
Intensity value to set. Must be either a single value or vector of same length as indices. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true on success. |
PointCloud.setIntensity(inputCloud, indices, intensity)
setPoint()
Sets the x, y, z and intensity value of the specified point in the point cloud.
| Name | Type | Description |
|---|---|---|
inputCloud |
OBJECT PointCloud |
Point cloud to set the point to |
index |
INT |
Point index starting from 0 |
x |
FLOAT |
X value in [mm] |
y |
FLOAT |
Y value in [mm] |
z |
FLOAT |
Z value in [mm] |
intensity |
FLOAT |
Intensity value, optional |
PointCloud.setPoint(inputCloud, index, x, y, z, intensity)
toImage()
Create a range image from a pointcloud. The image is formed by projection of the point in the pointcloud onto the z-zero plane with normal (0, 0, 1). The x and y axes of the pointcloud are aligned with the x and y axes of the resulting image. The employed method is sometimes referred to as splatting, i.e., each point in the pointcloud is splatted onto the plane, writing its z-distance to a splat area given in pixels. Pixels which are not hit by any splats are marked as missing data. If such holes appear in the generated image try increasing the splat sizes, make the pixel sizes larger or use methods to fill missing data. The function can return two images, one with the z-distance in each pixel and one with the intensity value from the pointcloud. The output image is of type UINT16 and the size of the image is calculated based on the input parameters. Image world coordinate system handling: The world coordinate settings, e.g., origin in x,y,z and pixel sizes are set based on the input parameters to the function. Missing data handling: Pixels in the output range image and intensity image will be zero (missing data) if no point in the pointcloud had effect over that pixel. Missing data can be reduced by increasing the splat size or by post processing.
convert, heightmap, project, splat
| Name | Type | Description |
|---|---|---|
pointcloud |
CONST_OBJECT PointCloud |
The input pointcloud. |
box |
CONST_OBJECT Shape3D |
An axis-aligned box. All pointcloud points within this box are used for creating the image. Can for example be the bounding box of the pointcloud to include all points. The coordinate system origin of the resulting image is defined by the box. |
pixelSizes |
FLOAT |
Vector defining the pixel sizes of the output image {x, y, z}. At least one value must be set and will then affect the x and y resolution. The z-resolution will be automatically estimated if unset. |
splatSizes |
INT |
Optional vector of splat kernel sizes in the x and y dimensions. To select a splat size of 5 use {5}, for anisotropic splatting use for example {3, 5}. Default is {3}. |
mode |
If several points in the pointcloud splat onto the same pixel, it must be choosen if the TOPMOST or BOTTOMMOST value is written to the result pixel. Default is TOPMOST. |
|
generateIntensity |
BOOL |
Select if an intensity image is to be generated also from the intensity part of the pointcloud. Defaults to true. |
| Name | Type | Description |
|---|---|---|
rangeImage |
OBJECT Image |
Output range image of UINT16 type. |
intensityImage |
OBJECT Image |
Intensity image of UINT8 type, if generated. |
rangeImageReference, intensityImage = PointCloud.toImage(pointcloud, boundingBox, {0.2})
toImageInplace()
Create a range image from a pointcloud. The image is formed by projection of the point in the point cloud onto the plane with normal (0, 0, 1). The x and y axes of the point cloud are aligned with the x and y axes of the resulting image. The employed method is sometimes referred to as splatting, i.e., each point in the pointcloud is splatted onto the plane, writing its z-distance to an splat area given in pixels. Pixels which are not hit by any splats are marked as missing data. If such holes appear in the generated image try increasing the splat sizes, make the pixel sizes larger or use methods to fill missing data. The operation is performed inplace for the input image, that is, the content of image will change inside the function. The function returns two images, one with the z-distance in each pixel and one with the intensity value from the pointcloud. Supported rangeImageReference types are unsigned integer images, i.e., UINT8, UINT16, UINT32 and UINT64. Image world coordinate system handling: The input image defines the world coordinate system and this image is updated and returned inplace. Make sure to set pixel sizes and origin to appropriate values before calling this function to achieve the desired result. Missing data handling: Pixels in the output range image and intensity image will be zero (missing data) if no point in the pointcloud had effect over that pixel. Missing data can be reduced by increasing the splat sizes or by post processing.
convert, heightmap, project, splat
| Name | Type | Description |
|---|---|---|
pointcloud |
CONST_OBJECT PointCloud |
The input pointcloud |
rangeImageReference |
OBJECT Image |
Both input and output image into which to render the result. Make sure to set pixel sizes and origin of this image to appropriate values before calling this function to achieve the desired result. |
splatSizes |
INT |
Optional vector of splat kernel sizes in the x and y dimensions. To select a splat size of 5 use {5}, for anisotropic splatting use for example {3, 5}. Default is {3}. |
mode |
If several points in the pointcloud splat onto the same pixel, it must be choosen if the TOPMOST or BOTTOMMOST value is written to the result pixel. Default is true. |
|
includeIntensity |
BOOL |
Select if an intensity image should also be generated. Defaults to true. |
| Name | Type | Description |
|---|---|---|
rangeImageReference |
OBJECT Image |
Reference to the output range image. |
intensityImage |
OBJECT Image |
The resulting intensity image, if generated. |
rangeImageReference, intensityImage = PointCloud.toImageInplace(pointcloud, rangeImageReference, {3}, "TOPMOST", true)
toPoints()
Returns the 3D coordinates of all points in the point cloud as vector of Point objects and the intensities as vector of float values.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
Point cloud to get the points from |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
3D coordinates as vector of Point objects. |
intensities |
FLOAT |
Intensities as vector of float values |
local points, intensities = PointCloud.toPoints(inputCloud)
toString()
Gets a user-friendly string description of the point cloud, containing important properties.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The point cloud to describe. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the point cloud. |
str = PointCloud.toString(inputCloud)
toVector()
Returns the x, y, z and intensity value of all points in the point cloud as vectors of float values.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
Point cloud to get the points from |
| Name | Type | Description |
|---|---|---|
x |
FLOAT |
X values in [mm] |
y |
FLOAT |
Y values in [mm] |
z |
FLOAT |
Z values in [mm] |
intensity |
FLOAT |
Intensity values |
local x,y,z,intensity = PointCloud.toVector(inputCloud)
transform()
Transform a point cloud. Fails if the transform is not a 3D transform.
| Name | Type | Description |
|---|---|---|
inputCloud |
CONST_OBJECT PointCloud |
The input point cloud. |
transform |
CONST_OBJECT Transform |
Transform to apply. |
| Name | Type | Description |
|---|---|---|
transformedCloud |
OBJECT PointCloud |
Transformed point cloud or nil on error |
local transformedCloud = PointCloud.transform(inputCloud, transform)
transformInplace()
In-place version of the PointCloud.transform function that modifies the input point cloud. See base function for full documentation.
| Name | Type | Description |
|---|---|---|
inputCloud |
OBJECT PointCloud |
The input point cloud. This point cloud is overwritten with the transformed point cloud. |
transform |
CONST_OBJECT Transform |
Transform to apply. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT PointCloud |
Reference to the result point cloud or nil on error. |
local result = PointCloud.transformInplace(inputCloud, transform)
PointCloud.Matching
Point cloud matching algorithms
Overview
PointCloud.Matching.Halcon
Point cloud matching algorithms based on Halcon
Overview
PointCloud.Matching.Halcon.SurfaceMatcher
Implements surface-based matching from Halcon. See operator create_surface_model for additional information. The surface model is created by resampling a teach object with a certain distance. The teach object can be either a PointCloud with additional normal information provided by a n by 4 Matrix or a Mesh. The sampling distance must be specified in the parameter relativeSamplingDistance and is parametrized relative to the diameter of the axis-parallel bounding box of the teach object. For example, if relativeSamplingDistance is set to 0.05 and the diameter of model is 100 mm, the points sampled from the object’s surface will be approximately 5 mm apart. The sampled points are used for the approximate matching in the match() call. Note that outlier points in the teach model should be avoided, as they would corrupt the diameter. Reducing relativeSamplingDistance leads to more points, and in turn to a more stable but slower matching. Increasing relativeSamplingDistance leads to fewer points, and in turn to a less stable but faster matching. The sampled points are used for finding the object model in a scene during a match() call. For this, all possible pairs of points from the point set are examined, and the distance and relative surface orientation of each pair is computed. Both values are discretized and stored for matching. The teach model is resampled a second time for the pose refinement. The second sampling is done with a smaller sampling distance, leading to more points. The parameter relativePoseRefinementSamplingDistance sets the sampling distance relative to the object’s diameter. Decreasing the value results in a more accurate pose refinement but a larger model and a slower model generation and matching. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. See Halcon’s operator find_surface_model for additional information. A minimum usage example is: local matcher = PointCloud.Matching.Halcon.SurfaceMatcher.create() local teachObject = matcher:teachMesh(teachMesh, 0.02) local scores, poses = PointCloud.Matching.Halcon.SurfaceMatcher.match(matcher, pointCloud) for index, score in ipairs(scores) do print(score, poses[index]:toString()) — transform the resampled teach model into the scene local teachObjectTransformed = teachObject:transform(poses[index]) end
The surface model is created by resampling a teach object with a certain distance. The teach object can be either a PointCloud with additional normal information provided by a n by 4 Matrix or a Mesh. The sampling distance must be specified in the parameter relativeSamplingDistance and is parametrized relative to the diameter of the axis-parallel bounding box of the teach object. For example, if relativeSamplingDistance is set to 0.05 and the diameter of model is 100 mm, the points sampled from the object’s surface will be approximately 5 mm apart. The sampled points are used for the approximate matching in the match() call. Note that outlier points in the teach model should be avoided, as they would corrupt the diameter. Reducing relativeSamplingDistance leads to more points, and in turn to a more stable but slower matching. Increasing relativeSamplingDistance leads to fewer points, and in turn to a less stable but faster matching.
The sampled points are used for finding the object model in a scene during a match() call. For this, all possible pairs of points from the point set are examined, and the distance and relative surface orientation of each pair is computed. Both values are discretized and stored for matching.
The teach model is resampled a second time for the pose refinement. The second sampling is done with a smaller sampling distance, leading to more points. The parameter relativePoseRefinementSamplingDistance sets the sampling distance relative to the object’s diameter. Decreasing the value results in a more accurate pose refinement but a larger model and a slower model generation and matching. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. See Halcons operator find_surface_model for additional information.
A minimum usage example is:
local matcher = PointCloud.Matching.Halcon.SurfaceMatcher.create()
local teachObject = matcher:teachMesh(teachMesh, 0.02)
local scores, poses = PointCloud.Matching.Halcon.SurfaceMatcher.match(matcher, pointCloud)
for index, score in ipairs(scores) do
print(score, poses[index]:toString())
-- transform the resampled teach model into the scene
local teachObjectTransformed = teachObject:transform(poses[index])
end
Overview
create(), getKeypointFraction(), getMaxMatches(), getMinScore(), getMinSeparation(), getNormalComputationMethod(), getPoseRefinementParameters(), getRelativeSamplingDistance(), match(), setKeypointFraction(), setMaxMatches(), setMinScore(), setMinSeparation(), setNormalComputationMethod(), setPoseRefinementParameters(), setRelativeSamplingDistance(), teachMesh(), teachPointCloud()
Functions
create()
Create a handle for the surface-based matching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
local matcher = PointCloud.Matching.Halcon.SurfaceMatcher.create()
getKeypointFraction()
Get the fraction of sampled scene points used as key points.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
| Name | Type | Description |
|---|---|---|
keypointFraction |
FLOAT |
fraction of sampled scene points used as key points. |
local keypointFraction = PointCloud.Matching.Halcon.SurfaceMatcher.getKeypointFraction(matcher)
getMaxMatches()
Gets the maximum number of matches that are returned.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
| Name | Type | Description |
|---|---|---|
maxMatches |
INT |
The maximum number of matches. |
local maxMatches = PointCloud.Matching.Halcon.SurfaceMatcher.getMaxMatches(matcher)
getMinScore()
Get the minimum score. The score is the relative number of sampled model points found in the matching. A model point is defined to be found if there is a scene point close to it.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
| Name | Type | Description |
|---|---|---|
minimumScore |
FLOAT |
Minimum score of the found matchings. |
local minimumScore = PointCloud.Matching.Halcon.SurfaceMatcher.getMinScore(matcher)
getMinSeparation()
Get the minimum relative overlap distance between matches.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
| Name | Type | Description |
|---|---|---|
overlapDistance |
FLOAT |
Minimum relative overlap distance between matches. |
local overlapDistance = PointCloud.Matching.Halcon.SurfaceMatcher.getMinSeparation(matcher)
getNormalComputationMethod()
Get the normal computation method
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
| Name | Type | Description |
|---|---|---|
type |
Normal computation method |
local type = PointCloud.Matching.Halcon.SurfaceMatcher.getNormalComputationMethod(matcher)
getPoseRefinementParameters()
Get parameters related to the dense pose refinement.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
| Name | Type | Description |
|---|---|---|
relativeDistanceThreshold |
FLOAT |
Distance threshold for dense pose refinement relative to the diameter of the surface model. |
relativeScoringThreshold |
FLOAT |
Distance threshold for scoring relative to the diameter of the surface model. |
local relativeDistanceThreshold, relativeScoringThreshold = PointCloud.Matching.Halcon.SurfaceMatcher.getPoseRefinementParameters(matcher)
getRelativeSamplingDistance()
Get the relative sampling distance for the point cloud input during matching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
| Name | Type | Description |
|---|---|---|
relativeSamplingDistance |
FLOAT |
Sampling distance relative to the diameter of point cloud input during matching. |
local relativeSamplingDistance = PointCloud.Matching.Halcon.SurfaceMatcher.getRelativeSamplingDistance(matcher)
match()
Perform the matching of the teach object in the point cloud: The matching is divided into three steps: 1.) Approximate matching: The approximate poses of the instances of the surface model in the scene are searched. 2.) Sparse pose refinement: In this second step, the approximate poses found in the previous step are further refined. This increases the accuracy of the poses and the significance of the score value. The sparse pose refinement uses the sampled scene points from the approximate matching. The pose is optimized such that the distances from the sampled scene points to the plane of the closest model point are minimal. The plane of each model point is defined as the plane perpendicular to its normal. 3.) Dense pose refinement: Accurately refines the poses found in the previous steps. This step works similar to the sparse pose refinement and minimizes the distances between the scene points and the planes of the closest model points.
The matching is divided into three steps:
-
Approximate matching: The approximate poses of the instances of the surface model in the scene are searched.
-
Sparse pose refinement: In this second step, the approximate poses found in the previous step are further refined. This increases the accuracy of the poses and the significance of the score value. The sparse pose refinement uses the sampled scene points from the approximate matching. The pose is optimized such that the distances from the sampled scene points to the plane of the closest model point are minimal. The plane of each model point is defined as the plane perpendicular to its normal.
-
Dense pose refinement: Accurately refines the poses found in the previous steps. This step works similar to the sparse pose refinement and minimizes the distances between the scene points and the planes of the closest model points.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
pointCloud |
CONST_OBJECT PointCloud |
The point cloud for matching. |
| Name | Type | Description |
|---|---|---|
score |
FLOAT |
The score is between 0 and 1. Relative number of sampled model points found in the matching. A model point is defined to be found if there is a scene point close to it. |
pose |
OBJECT Transform |
The pose for the teach object in the matching result. |
local score, pose = PointCloud.Matching.Halcon.SurfaceMatcher.match(matcher, pointCloud)
setKeypointFraction()
Set the fraction of sampled scene points used as key points. A set of key points is selected from the sampled scene points. The number of selected key points is controlled with the parameter keypointFraction. Increasing keypointFraction means that more key points are selected from the scene, resulting in a slower but more stable matching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
keypointFraction |
FLOAT |
Fraction of sampled scene points used as key points. Must be between 0 and 1. Default is 0.2. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True on success, false if parameters where invalid. |
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setKeypointFraction(matcher, keypointFraction)
setMaxMatches()
Sets the maximum number of matches that are returned.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
maxMatches |
INT |
The maximum number of matches. Must be larger than 0. Default is 1. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True on success, false if parameters where invalid. |
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setMaxMatches(matcher, maxMatches)
setMinScore()
Set the minimum score. The score is the relative number of sampled model points found in the matching. A model point is defined to be found if there is a scene point close to it.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
minimumScore |
FLOAT |
Minimum score of the found matchings. Must be positive. Default is 0. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True on success, false if parameters where invalid. |
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setMinScore(matcher, minimumScore)
setMinSeparation()
Set the minimum relative overlap distance between matches. The distance is computed as the diference between the matches axis-aligned bounding boxes.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
overlapDistance |
FLOAT |
Minimum relative overlap distance between matches. Must be non-negative. Default is 0.5. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True on success, false if parameters where invalid. |
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setMinSeparation(matcher, overlapDistance)
setNormalComputationMethod()
Set the normal computation method
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
type |
Normal computation method. Default is 'FAST'. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True on success, false if parameters where invalid. |
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setNormalComputationMethod(matcher, type)
setPoseRefinementParameters()
Set parameters related to the dense pose refinement.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
relativeDistanceThreshold |
FLOAT |
Distance threshold for dense pose refinement relative to the diameter of the surface model. Only scene points that are closer to the object than this distance are used for the optimization. Must be larger than zero. Default is 0.005. |
relativeScoringThreshold |
FLOAT |
Distance threshold for scoring relative to the diameter of the surface model. Only scene points that are closer to the object than this distance are considered to be 'on the model' when computing the score after the pose refinement. Must be larger than zero. Default is 0.05. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True on success, false if parameters where invalid. |
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setPoseRefinementParameters(matcher, relativeDistanceThreshold, relativeScoringThreshold)
setRelativeSamplingDistance()
Set the relative sampling distance for the point cloud input during matching.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
relativeSamplingDistance |
FLOAT |
Sampling distance relative to the diameter of point cloud input during matching. Must be between 0 and 1. Default is 0.05. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True on success, false if parameters where invalid. |
local success = PointCloud.Matching.Halcon.SurfaceMatcher.setRelativeSamplingDistance(matcher, relativeSamplingDistance)
teachMesh()
Teach a model for matching from a mesh object.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
mesh |
CONST_OBJECT Mesh |
Mesh representing the teach object. |
relativeSamplingDistance |
FLOAT |
Sampling distance relative to axis-parallel bounding box used for sampling the teach model. |
relativePoseRefinementSamplingDistance |
FLOAT |
Set the sampling distance for the pose refinement relative to the teach object’s diameter. Decreasing this value leads to a more accurate pose refinement but a larger model and slower model generation and refinement. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. Default is 0.01. |
| Name | Type | Description |
|---|---|---|
sampledTeachObject |
OBJECT PointCloud |
The resampled point cloud that is used for the approximate matching in the match() call. |
local teachObject = PointCloud.Matching.Halcon.SurfaceMatcher.teachMesh(matcher, mesh, relativeSamplingDistance, relativePoseRefinementSamplingDistance)
teachPointCloud()
Teach a model for matching from a point cloud and normal information.
| Name | Type | Description |
|---|---|---|
matcher |
HANDLE |
Handle for matcher. |
pointCloud |
CONST_OBJECT PointCloud |
Point cloud with n points representing the teach object. |
normals |
CONST_OBJECT Matrix |
The normals represented as n x 4 matrix. |
relativeSamplingDistance |
FLOAT |
Sampling distance relative to axis-parallel bounding box used for sampling the teach model. |
relativePoseRefinementSamplingDistance |
FLOAT |
Set the sampling distance for the pose refinement relative to the teach object’s diameter. Decreasing this value leads to a more accurate pose refinement but a larger model and slower model generation and refinement. Increasing the value leads to a less accurate pose refinement but a smaller model and faster model generation and matching. Default is 0.01. |
| Name | Type | Description |
|---|---|---|
sampledTeachObject |
OBJECT PointCloud |
The resampled point cloud that is used for the approximate matching in the match() call. |
local teachObject = PointCloud.Matching.Halcon.SurfaceMatcher.teachPointCloud(matcher, pointCloud, normals, relativeSamplingDistance, relativePoseRefinementSamplingDistance)
PointCloud.RangeFilter
Removes points outside of the defined attribute range (or inside, if the behavior is inverted with setNegative(true)). By default, the filter does not remove any points.
Overview
Functions
create()
Create a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
local handle = PointCloud.RangeFilter.create()
filter()
Return the area filtered PointCloud.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
inputCloud |
CONST_OBJECT PointCloud |
The PointCloud object which is filtered |
| Name | Type | Description |
|---|---|---|
filteredCloud |
OBJECT PointCloud |
The area filtered PointCloud |
local areaCloud = PointCloud.RangeFilter.filter(handle, cloud)
setIntensityRange()
Set the filter range for intensity values. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
minIntensity |
FLOAT |
Minimum intensity value in range [0.0-1.0] |
maxIntensity |
FLOAT |
Maximum intensity value in range [0.0-1.0] |
PointCloud.RangeFilter.setIntensityRange(handle, 0.8, 1.0)
setNegative()
Set to true to invert the filter behavior (return points outside of range).
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
behavior |
BOOL |
Invert filter behavior, default is false |
PointCloud.RangeFilter.setNegative(handle, true)
setXRange()
Set the filter range in x-direction. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
minX |
FLOAT |
Minimum x value |
maxX |
FLOAT |
Maximum x value |
PointCloud.RangeFilter.setXRange(handle, -10.5, 15.0)
setYRange()
Set the filter range in y-direction. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
minY |
FLOAT |
Minimum y value |
maxY |
FLOAT |
Maximum y value |
PointCloud.RangeFilter.setYRange(handle, -10.5, 15.0)
setZRange()
Set the filter range in z-direction. Points outside of this range are filtered out. If both parameters are 0 (default), the filter is disabled.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
minZ |
FLOAT |
Minimum z value |
maxZ |
FLOAT |
Maximum z value |
PointCloud.RangeFilter.setZRange(handle, -10.5, 15.0)
Profile
A data type for vector of 1D measurements. Three main components of the data type are - A vector of measurement values represented in 32 bit float precision. - An optional vector of valid flags indicating if the measurement value at the same index is valid. An integer representation is used where 0 means invalid and 1 means valid measurement. A global flag indicates if algorithms must consider the valid flags vector at all in computations. - Coordinate information for each measurement value, relating the measurement to a world position (temporal or spatial). The main purpose of the Profile type is for 1D processing, e.g., filtering finding peaks and edges, analyze trends, matching 1D patterns etc. Processing is done on the measurement vector, taking the valid flag vector into account if enabled. The purpose of the coordinate vector is to relate the measurements with a world position. The world position can be both temporal or spatial, e.g., time, angle or 2D (x,y) position. The following three examples illustrate possible use cases for the Profile type: Example 1: The measurement values represent the number of sent packages in a logistics center each day. The coordinate information represents time (day) and the valid flags vector if there was a valid package count on the corresponding day. Example 2: The measurements are range values from a LiDAR scan in polar format. The coordinate is the angle for each range measurement. The valid flag vector indicates whether the corresponding range value is valid, e.g., if there was a reliable "echo" received. Example 3: The measurement values are the height values sampled evenly along a straight line in a heightmap image. The coordinate vector in this case is a (x,y) world coordinate in millimeters or pixels, where each height value was sampled. As heightmaps can contain missing data pixels (no height value available), the valid flag vector carries this information. The coordinate information can be represented in different ways: An implicit representation stores a start coordinate (1D float value or 2D point) and a constant delta (1D float value or 2D vector). An explicit representation stores the coordinate (1D float value or 2D point) in a vector of the same length as the measurement vector. How the coordinate information is represented is determined when the Profile object is created. There is also a 'isClosed'-flag indicating if the coordinates wraps around so that the first and last samples are neighbors. This can happen for example for a 360 degree LiDAR scan or if one samples height values from a circle in a heightmap. This has effect in certain filtering operations where neighboring samples are considered to produce an output.
Keywords
1d, array, scan, vector
Overview
abs(), absInplace(), add(), addConstant(), addConstantInplace(), addInplace(), addNoise(), addNoiseInplace(), aggregate(), binarize(), binarizeInplace(), blur(), centralDifference(), clamp(), clampInplace(), clone(), concatenate(), concatenateInplace(), convertCoordinateType(), convolve(), create(), createFromPoints(), createFromVector(), crop(), difference(), differenceInplace(), divide(), divideInplace(), fillInvalidValues(), fillInvalidValuesWithReference(), findEqual(), findLocalExtrema(), findRangeEdges(), fourierTransform(), fourierTransformInverse(), gauss(), gaussDerivative(), getArea(), getClosed(), getCoordinate(), getCoordinateType(), getDistance(), getHistogram(), getIntersectionAngle(), getMax(), getMean(), getMedian(), getMin(), getSize(), getStandardDeviation(), getSum(), getValidCount(), getValidFlag(), getValidFlagsEnabled(), getValue(), interpolateCoordinate(), load(), median(), mirror(), mirrorInplace(), multiply(), multiplyAddConstant(), multiplyAddConstantInplace(), multiplyConstant(), multiplyConstantInplace(), multiplyInplace(), pow(), powInplace(), removeValidFlagVector(), resize(), resizeScale(), rotate(), rotateInplace(), save(), setClosed(), setCoordinate(), setImplicitCoordinates(), setValidFlag(), setValidFlagRange(), setValidFlagsEnabled(), setValue(), shrink(), shrinkInplace(), sort(), subtract(), subtractInplace(), threshold(), toImage(), toString(), toVector(), translate(), translateInplace()
Functions
abs()
Computes the absolute value of each measurement in the profile. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.
absolute
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The resulting profile. |
local result = Profile.abs(profile)
absInplace()
In-place version of the Profile.abs function that modifies the input profile. See base function for full documentation.
absolute
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The source profile. This profile is overwritten with the result of the abs. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.absInplace(profile)
add()
Adds two profiles sample-wise. The two profiles must have the same number of measurements. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.
plus
| Name | Type | Description |
|---|---|---|
profile1 |
CONST_OBJECT Profile |
The first source profile. |
profile2 |
CONST_OBJECT Profile |
The second source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The resulting profile. |
local result = Profile.add(profile1, profile2)
addConstant()
Adds a constant to the measurements of the profile. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.
translate, shift
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
constant |
FLOAT |
The constant to add. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The resulting profile. |
local result = Profile.addConstant(profile, constant)
addConstantInplace()
In-place version of the Profile.addConstant function that modifies the input profile. See base function for full documentation.
translate, shift
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The source profile. This profile is overwritten with the result of the sum. |
constant |
FLOAT |
The constant to add. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.addConstantInplace(profile, constant)
addInplace()
In-place version of the Profile.add function that modifies the input profile. See base function for full documentation.
plus
| Name | Type | Description |
|---|---|---|
profile1 |
OBJECT Profile |
The first source profile. This profile is overwritten with the result of the sum. |
profile2 |
CONST_OBJECT Profile |
The second source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.addInplace(profile1, profile2)
addNoise()
Adds noise to profile values. Noise with normal or uniform distribution can be selected. noiseType NORMAL: param1: standard deviation. param2: mean. noiseType UNIFORM: param1: Minimum value. param2: Maximum value.
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
noiseType |
ENUM NoiseType |
Distribution of noise. NORMAL or UNIFORM. |
param1 |
FLOAT |
Standard deviation if noiseType NORMAL (Default value 1.0). Min value if noiseType UNIFORM (Default value -1.0). |
param2 |
FLOAT |
Mean value if noiseType NORMAL (Default value 0.0). Max value if noiseType UNIFORM (Default value 1.0). |
randSeed |
INT |
Random seed, optional. No new seed is set if negative. Default: 0 |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Profile with noise added. |
local result = Profile.addNoise(profile, noiseType, param1, param2, randSeed)
addNoiseInplace()
In-place version of addNoise. See base function for full documentation.
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile to add noise to. |
noiseType |
ENUM NoiseType |
Distribution of noise. NORMAL or UNIFORM. |
param1 |
FLOAT |
Standard deviation if noiseType NORMAL (Default value 1.0). Min value if noiseType UNIFORM (Default value -1.0). |
param2 |
FLOAT |
Mean value if noiseType NORMAL (Default value 0.0). Max value if noiseType UNIFORM (Default value 1.0). |
randSeed |
INT |
Random seed, optional. No new seed is set if negative. Default: 0 |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the profile with noise added. |
local result = Profile.addNoiseInplace(profile, noiseType, param1, param2, randSeed)
aggregate()
Aggregate a set of profiles into one profile. Different aggregation operations are available such as sum, mean, min, max and median. All profiles must have the same number of measurements. All or none of the profiles must use the valid data flags. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Invalid values are excluded from the aggregation, e.g. the mean value is the mean of the valid values at a given position in the profiles. If no profile has a valid value at a particular index, the output profile will have an invalid value at that index. A profile containing the number of valid samples used in the aggregation at each index is returned. If no profile has invalid values, the valid samples profile will be constant and equal to the number of input profiles.
max, mean, median, min, sum
| Name | Type | Description |
|---|---|---|
profiles |
CONST_OBJECT Profile |
The source profiles. |
operation |
ENUM AggregateOperation |
The type of operation used to generate the aggregate. |
| Name | Type | Description |
|---|---|---|
aggregateProfile |
OBJECT Profile |
The aggregated profile. |
validValuesProfile |
OBJECT Profile |
The number of entries used for each aggregated sample. |
local aggregateProfile, validValuesProfile = Profile.aggregate(profiles, operation)
binarize()
Applies a threshold interval (lowerThreshold, upperThreshold) to the profile to create a binary profile. Measurement values outside the interval have the value 0 in the output profile, and values within the interval have a user-specified value. Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: If a measurement is invalid in the input profile it is invalid in the output profile.
threshold
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
lowerThreshold |
FLOAT |
Lower threshold for the binarization. |
upperThreshold |
FLOAT |
Upper threshold for the binarization. |
outputValue |
FLOAT |
Value assigned to the measurements within the threshold interval. Optional, default value is 1. |
| Name | Type | Description |
|---|---|---|
binarizedProfile |
OBJECT Profile |
Binarized profile. |
local binarizedProfile = Profile.binarize(profile, lowerThreshold, upperThreshold, outputValue)
binarizeInplace()
In-place version of the Profile.binarize function that modifies the input profile. See base function for full documentation.
threshold
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The source profile. This profile is overwritten with the binarized result. |
lowerThreshold |
FLOAT |
Lower threshold for the binarization. |
upperThreshold |
FLOAT |
Upper threshold for the binarization. |
outputValue |
FLOAT |
Value assigned to the measurements within the threshold interval. Optional, default value is 1. |
| Name | Type | Description |
|---|---|---|
binarizedProfile |
OBJECT Profile |
Reference to the result profile. |
local binarizedProfile = Profile.binarizeInplace(profile, lowerThreshold, upperThreshold, outputValue)
blur()
Smooths a profile using a constant normalized box filter kernel of the given size. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Only the valid measurements are considered in the calculation. By default, all invalid measurements will be marked as invalid also in the output. If the fill flag is set to true, invalid measurements will be filled with filtered neighbor values where possible.
box, filter, gauss, low pass, lp, smooth
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
Input profile. |
kernelSize |
INT |
Size of the kernel, must be positive, odd and smaller than the profile length. |
fillInvalid |
BOOL |
Optional flag to also fill in invalid values while filtering. Default is false. |
| Name | Type | Description |
|---|---|---|
smoothProfile |
OBJECT Profile |
Output profile, smoothed by the blur filter. |
local smoothProfile = Profile.blur(profile, kernelSize)
centralDifference()
Differentiate a profile using a first- or second-order central finite difference filter kernel. A step parameter determines how far from the center the difference is taken: First order difference: Step 1: [1 0 -1] Step 2: [1 0 0 0 -1] and so on. Second order difference: Step 1: [1 -2 1] Step 2: [1 0 -2 0 1] and so on. The output is set to zero in the beginning and end of the output profile, where the entire filter does not fit within the profile. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: If the valid data flags are enabled, the output is set as invalid if any non-zero filter coefficient hits an invalid input value or is out of bounds. For example, if differenceStep=1, the first and last output values is always set as invalid, since the 1 and -1 filter coefficients are out of bounds of the input profile.
first, gradient, second, slope, derivative
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
Input profile. |
differenceStep |
INT |
How far from the center the kernel weights are placed, must be strictly positive. |
order |
ENUM DifferentiationOrder |
FIRST gives first order derivative and SECOND gives second order derivative. |
| Name | Type | Description |
|---|---|---|
diffProfile |
OBJECT Profile |
Output profile created by the central difference filter. |
local diffProfile = Profile.centralDifference(profile, differenceStep, order)
clamp()
Clamps each measurement value to an interval (minValue, maxValue). Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.
threshold, limit
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
minValue |
FLOAT |
The minimum value to clamp to. |
maxValue |
FLOAT |
The maximum value to clamp to. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The clamped profile. |
local result = Profile.clamp(profile, minValue, maxValue)
clampInplace()
In-place version of the Profile.clamp function that modifies the input profile. See base function for full documentation.
threshold, limit
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The source profile. This profile is overwritten with the clapped result. |
minValue |
FLOAT |
The minimum value to clamp to. |
maxValue |
FLOAT |
The maximum value to clamp to. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.clampInplace(profile, minValue, maxValue)
clone()
Creates an independent copy of a profile.
copy
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
Input profile. |
| Name | Type | Description |
|---|---|---|
clonedProfile |
OBJECT Profile |
Copy of the input profile. |
local clonedProfile = Profile.clone(profile)
concatenate()
Concatenates two profiles. The profiles must have the same coordinate type. Periodic flag and implicit coordinates are copied from the first profile. If any of the two profiles uses valid flags the result also does so.
merge, join
| Name | Type | Description |
|---|---|---|
profile1 |
CONST_OBJECT Profile |
The source profile 1. |
profile2 |
CONST_OBJECT Profile |
The source profile 2. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Concatenated profile. |
local result = Profile.concatenate(profile1, profile2)
concatenateInplace()
In-place version of concatenate that modifies the first input profile. See base function for full documentation.
merge, join
| Name | Type | Description |
|---|---|---|
profile1 |
OBJECT Profile |
The source profile 1 and result profile. |
profile2 |
CONST_OBJECT Profile |
The source profile 2. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the concatenated profile. |
local result = Profile.concatenateInplace(profile1, profile2)
convertCoordinateType()
Converts sample coordinates in the profile. Possible coordinate types: IMPLICIT_1D, EXPLICIT_1D, IMPLICIT_2D, EXPLICIT_2D. Note that the values in the profile are kept unchanged. Implicit to explicit: Change the coordinate representation from start + delta representation, to vector with absolute positions. Explicit to implicit: Change the coordinate representation from vector with absolute coordinates, to a start + delta representation. Preserving the coordinates for the first and last sample. 1D to 2D: The 1D coordinates are placed on the x-axis in the 2D coordinates. 2D to 1D: The accumulated curve length in 2D is used as the new 1D coordinates. Thus, start position is 0.0.
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile object. |
coordinateType |
ENUM CoordinateType |
New coordinate type. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.convertCoordinateType(profile, coordinateType)
convolve()
Convolves a profile with a given filter kernel. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Invalid flags are not allowed in this operation.
filter
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
Input profile. |
kernel |
FLOAT |
Filter kernel. Must be shorter than the profile. |
| Name | Type | Description |
|---|---|---|
filteredProfile |
OBJECT Profile |
Output profile, filtered with the kernel. |
local filteredProfile = Profile.convolve(profile, kernel)
create()
Creates a new Profile object with all measurements set to a constant value. Coordinate system handling: The coordinate representation will be implicit 1D, starting at 0 with a delta value of 1. Valid flags handling: All measurements are considered as valid. No valid flags vector is created.
| Name | Type | Description |
|---|---|---|
size |
INT |
The number of measurements in the profile. |
constantValue |
FLOAT |
The fill value, default is 0. |
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The new profile. |
local profile = Profile.create(size, constantValue)
createFromPoints()
Creates a new profile from a vector of points. Coordinate system handling: For 2D points the profile will have EXPLICIT_1D coordinates, where the x-coordinates will become the coordinates in the Profile and the y-coordinates will become the corresponding values. For 3D points the profile will have EXPLICIT_2D coordinates, where the x,y-coordinates will become the coordinates in the Profile and the z-coordinates will become the corresponding values.
convert
| Name | Type | Description |
|---|---|---|
points |
CONST_OBJECT Point |
The vector of points. |
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The new profile. |
local profile = Profile.createFromPoints(points)
createFromVector()
Creates a new profile from a vector of measurement values, coordinates and valid flags. Coordinate system handling: The coordinate vector is optional, if not supplied 1D implicit coordinates starting at 0 with delta 1 is created. If supplied it can be both a float vector or a vector of 2D Points. An explicit coordinate representation is then created. Valid flags handling: The valid flags vector is optional. If no vector is supplied the global flag to use the valid flags is turned off. If supplied it must have the same length as the measurement vector, with 0 meaning that the corresponding measurement is invalid and non-zero that it is valid.
convert
| Name | Type | Description |
|---|---|---|
values |
FLOAT |
The vector of measurement values. |
coordinates |
CONST_AUTO |
Optional vector of world coordinates (float or 2D points). |
flags |
INT |
Optional vector of valid flags of the same length as the measurement vector. |
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The new profile. |
local profile = Profile.createFromVector(values, coordinates, flags)
crop()
Creates a new profile by cropping a segment of another profile. Coordinate system handling: The coordinate representation of the output profile is modified: If an implicit coordinate representation is used, the start coordinate is adjusted. If an explicit representation is used, the coordinate vector is cropped accordingly. Valid flags handling: The valid flags vector is cropped also if it exists.
range, sub profile, region
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
Input profile |
startIndex |
INT |
The start index, zero-based indexing. |
stopIndex |
INT |
The end index, zero-based indexing. |
| Name | Type | Description |
|---|---|---|
croppedProfile |
OBJECT Profile |
The new cropped profile. Returns nil if any index is out-of-range or if stop index is smaller than start index. |
local croppedProfile = Profile.crop(profile, startIndex, stopIndex)
difference()
Calculates the absolute or squared difference between two profiles, sample-wise. The two profiles must have the same number of samples. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.
ssd, sad
| Name | Type | Description |
|---|---|---|
profile1 |
CONST_OBJECT Profile |
The first source profile. |
profile2 |
CONST_OBJECT Profile |
The second source profile. |
mode |
ENUM DifferenceMode |
Absolute or squared difference (ABS or SQUARE). |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The difference profile. |
local result = Profile.difference(profile1, profile2, mode)
differenceInplace()
In-place version of the Profile.difference function that modifies the input profile. See base function for full documentation.
ssd, sad
| Name | Type | Description |
|---|---|---|
profile1 |
OBJECT Profile |
The first source profile. This profile is overwritten with the result of the difference. |
profile2 |
CONST_OBJECT Profile |
The second source profile. |
mode |
ENUM DifferenceMode |
Absolute or squared difference (ABS or SQUARE). |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.differenceInplace(profile1, profile2, mode)
divide()
Divides the first profile with the second, sample-wise. The two profiles must have the same number of samples. If division-by-zero occurs, the corresponding output is set to zero. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: The valid flags of the output are enabled if any of the inputs have their flags enabled. Both input profiles must have a valid measurement to produce a valid output for an index. If output valid flags are enabled, division-by-zero sets the corresponding valid flag to false.
| Name | Type | Description |
|---|---|---|
profile1 |
CONST_OBJECT Profile |
The first source profile. |
profile2 |
CONST_OBJECT Profile |
The second source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The resulting profile. |
local result = Profile.divide(profile1, profile2)
divideInplace()
In-place version of the Profile.divide function that modifies the input profile. See base function for full documentation.
| Name | Type | Description |
|---|---|---|
profile1 |
OBJECT Profile |
The first source profile. This profile is overwritten with the result of the division. |
profile2 |
CONST_OBJECT Profile |
The second source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.divideInplace(profile1, profile2)
fillInvalidValues()
Fills in invalid values in a profile using neighboring valid values. A number of different ways interpolation methods are available: LINEAR: Fills invalid values using linear interpolation. Maximum length of invalid value region can be specified with fillParam. N invalid in a row is filled if N is smaller or equal to fillParam. All invalid are filled if fillParam is unspecified. NEIGHBOR_MIN: Fills invalid values with the min value of the two neighboring valid values. NEIGHBOR_MAX: Fills invalid values with the max value of the two neighboring valid values. NEIGHBOR_MEAN: Fills invalid values with the mean value of the two neighboring valid values. Valid flags handling: If no maximum length of invalid regions is specified all invalid values are filled and UseValidFlag is set to false.
interpolation, missing data
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
fillMethod |
ENUM FillInvalidMethod |
Method to use when filling invalid values. |
maxGap |
INT |
Maximum gap of invalid samples to fill. Default: infinite. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The filled profile. |
local result = Profile.fillInvalidValues(profile, fillMethod, maxGap)
fillInvalidValuesWithReference()
Fills invalid values with corresponding values in a reference profile. Valid flags handling: All samples in the reference profile is assumed to be valid. Thus, a invalid sample in the input profile is always replaced with corresponding value in the reference profile. UseValidFlag is set to false in result profile.
interpolation, missing data
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
referenceProfile |
CONST_OBJECT Profile |
The reference profile of equal length as the source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The filled profile. |
local result = Profile.fillInvalidValuesWithReference(profile, referenceProfile)
findEqual()
Finds elements in a profile equal to a given value, within a give tolerance. Valid flags handling: Only the valid measurements are considered in the calculation.
value, search
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
value |
FLOAT |
Value to find. |
epsilon |
FLOAT |
Tolerance interval. Default: eps of float32 |
| Name | Type | Description |
|---|---|---|
indices |
INT |
Indices of found elements. |
local indices = Profile.findEqual(profile, value, epsilon)
findLocalExtrema()
Finds local extreme points (minima or maxima) of a Profile. A point is a local maximum if it is larger than all points within a neighborhood of the specified size. An optional contrast threshold level can be defined that sets a required value difference between the local maximum and the values on each side of the maximum, within the neighborhood. For locally maximal plateaus, where several measurements in the profile have the exact same value, only the leftmost value is reported. An optional absolute threshold can be specified, if so, point values must exceed the absolute threshold to be reported. Local minima are detected in a similar way. If contrastDifferenceMode ONE is selected (default), there must be at least one valid value on each side that is further from the extremal point than contrastThreshold. If contrastDifferenceMode ALL is selected, there must be at least one valid value on each side, and all valid values must be further from the extremal point than contrastThreshold. For non-closed profiles, the entire neighborhood must fit within the profile. E.g., if neighborhoodSize = 5, no extreme points will be detected at the first and last 2 measurements. Closed profiles are handled by wrap-around of the neighborhood. Coordinate system handling: The coordinate representation is not considered in this operation, the indices of the extremal points are returned. Valid flags handling: A maxima or minima can never be reported at positions with invalid data, but invalid data can be contained in the local neighborhood around a reported extreme point. When determining if a point is an extreme point, invalid data points within the local neighborhood are ignored.
extreme, local maximum, local minimum, valley, peak
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
extremaType |
ENUM ExtremaType |
Which type of extrema to look for. MIN or MAX. |
neighborhoodSize |
INT |
The neighborhood size, expressed as number of samples. Must be odd and >= 3. Default is 3. |
contrastThreshold |
FLOAT |
Required height of the peak/valley (value difference between the extreme point and surrounding points). Set to zero to disable (default). |
contrastDifferenceMode |
Determines how the difference between the extreme point and the surrounding points is calculated. Default is ONE, there must be at least one valid value on each side that is further from the extremal point than contrastThreshold. |
|
absoluteThreshold |
FLOAT |
Absolute threshold, extremal points must be beyond this value to be included in the output. By default, this threshold is not used. |
| Name | Type | Description |
|---|---|---|
extremaPositions |
INT |
Positions of the detected min or max points expressed as sample indices (zero-based). Nil if invalid parameters are provided. |
local extremaPositions = Profile.findLocalExtrema(profile, extremaType, neighborhoodSize, contrastThreshold, contrastDifferenceMode, absoluteThreshold)
findRangeEdges()
Finds points in a range data profile that are likely to correspond to edges of physical objects. Although this function can be run on profiles from any source, it is developed with range data from laser devices in mind. The algorithm looks for points where the profile has a sharp knee near a discontinuity or fast transition between a low and a high level. A differenceStep parameter determines the width over which the value transition is measured, i.e., Step 1: [1 0 -1], Step 2: [1 0 0 0 -1], and so on. This parameter should be tuned such that the filter spans the entire low-high transition. Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: If side = HIGH, this function reports edge points at transitions between valid and invalid measurements. This is because the low side of a physical 3D edge often contains invalid measurements due to shadowing of the laser line. For edges detected at such transitions between valid and invalid measurements, the minStrength parameter is ignored. If side = LOW, edges are only reported where the non-zero filter coefficients hit valid measurements.
corner, discontinuity, step
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
differenceStep |
INT |
The central difference step. |
polarity |
ENUM SlopePolarity |
Slope polarity. POSITIVE (rising slope) or NEGATIVE (falling slope). |
minStrength |
FLOAT |
Threshold on the magnitude central difference filter response. Only slopes with a strength larger than this threshold are reported. |
side |
ENUM EdgeSide |
Side of the range edge (HIGH or LOW side). |
| Name | Type | Description |
|---|---|---|
subsampleIndex |
FLOAT |
Index with subsample (float) precision of the found edge points. Nil if invalid parameters are provided. |
local subsampleIdx = Profile.findRangeEdges(profile, differenceStep, polarity, minStrength, side)
fourierTransform()
Calculates the Fourier transform of a profile. A sampled Fourier transform is returned distributed over one profile with magnitude values and one profile with phase values. The coordinates of the output profiles are adjusted to fit the input profile coordinates. E.g. if the input coordinates are in seconds, the output profile coordinates are in Hertz. If the input coordinates are in meters, the output coordinates are in cycles per meter and so on. The input profile coordinates must be of type implicit 1D (see Profile.setImplicitCoordinates). Missing values are not supported. The input profile can be zero-padded to a given length to increase the apparent frequency resolution of the output. If the transformLength parameter is smaller than the length of the input profile, the full input profile is used and no padding occurs. Set the smoothWindow flag true to apply a smooth window function to the profile prior to transformation. Using a smooth window makes the side lobes decay faster but also makes the main lobe wider and lower, i.e. low amplitude components become easier to detect but frequencies close to each other may merge into the same peak in the amplitude spectrum. Only the positive-frequency half spectrum is returned as the input is a real signal. The output frequency range is from zero to half the sampling frequency 0.5 * 1/T, where T is the sample distance of the input profile (for even size input profiles). N/2 + 1 output samples are created, where N is the number of input samples. If the first sample of the input profile is not at coordinate zero, the output phase is adjusted to match the translation of the input. Magnitude values are normalized to match the DC-level and half the amplitude of pure sinusoidal inputs, i.e. the transform of the profile a + b*sin(2*pi*f*t) will have a magnitude profile with value a at zero and value b/2 at f. Valid flags handling: Only profiles with disabled validity flags are allowed. Raw DFT mode: By setting the rawDFT flag true, most checks of the input and all scaling of the output are removed and a DFT is performed directly on all the values in the input profile. The transformLength parameter is ignored and no smoothed window is used. Coordinates and validity flags are ignored and the output coordinate system is not related to frequencies. The result is returned in Cartesian form, the first profile with the real part and the second profile contains the imaginary part. The full spectrum is returned, the first sample is the DC-component.
dft, frequency, spectrum, fft
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
smoothWindow |
BOOL |
If set, a smooth window function (Hann window) is applied to the profile prior to transformation. Default is false, i.e. a box window is used. Ignored in raw mode. |
transformLength |
INT |
The target transform length, if the input profile is shorter it is zero padded. Ignored in raw mode. |
rawDFT |
BOOL |
Set to true to use raw DFT mode, default is false. |
| Name | Type | Description |
|---|---|---|
magnitude |
OBJECT Profile |
The magnitude profile. The real part in raw mode. |
phase |
OBJECT Profile |
The phase profile. The imaginary part in raw mode. |
local magnitude, phase = Profile.fourierTransform(profile, smoothWindow, transformLength, rawDFT)
fourierTransformInverse()
Calculates the inverse Fourier transform. This function is the inverse of fourierTransform(), taking one magnitude profile and one phase profile and calculating the corresponding profile. The input profiles should have the first frequency sample at 0 and the last frequency sample at half the time domain sampling frequency, as created by fourierTransform(). The output is always calculated starting at zero offset and will have 2*(N-1) samples, where N is the number of samples in the input. The output coordinate system matches the input coordinate system, e.g. if the input coordinates are in hertz, the output coordinates are in seconds. If the coordinate systems specified in the magnitude profile and phase profile differ, the magnitude coordinate system is used. Note that this means that the returned profile will always have an even number of samples even if the originally transformed profile had an odd number of samples. Further, this function always recreates the part of the signal starting at time/position zero, which may not be where the original profile was sampled. Valid flags handling: Only profiles with disabled validity flags are allowed. Raw DFT mode: By setting the rawDFT flag true, most checks of the input and all scaling of the output are removed and an IDFT is performed directly on all the values in the input profile. In raw mode, input is expected to be in Cartesian form (first profile is the real part, second profile is the imaginary part) and the full spectrum is expected, starting with the DC component at the first sample. Coordinates and validity flags are ignored and the output coordinate system is not related to the input. The result is returned in Cartesian form, the first profile with the real part and the second profile contains the imaginary part.
frequency, idft, spectrum, ifft
| Name | Type | Description |
|---|---|---|
magnitude |
CONST_OBJECT Profile |
The input magnitude profile. The real part in raw mode. |
phase |
CONST_OBJECT Profile |
The input phase profile. The imaginary part in raw mode. |
rawDFT |
BOOL |
Set to true to use raw DFT mode, default is false. |
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The resulting profile. The real part of the result in raw mode. |
imaginaryPart |
OBJECT Profile |
Only used in raw mode, the imaginary part of the result. |
local profile, imaginaryPart = Profile.fourierTransformInverse(magnitude, phase, rawDFT)
gauss()
Smooths a profile using a Gauss filter kernel. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Only the valid measurements are considered in the calculation. By default, all invalid measurements will be marked as invalid also in the output. If the fill flag is set to true, invalid measurements will be filled with filtered neighbor values where possible.
filter, low pass, lp, smooth
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
Input profile. |
kernelSize |
INT |
Size of the kernel, must be positive, odd and smaller than the profile length. |
fillInvalid |
BOOL |
Optional flag to also fill in invalid values while filtering. Default is false. |
| Name | Type | Description |
|---|---|---|
smoothProfile |
OBJECT Profile |
Output profile, smoothed by the Gauss filter. |
local smoothProfile = Profile.gauss(profile, kernelSize)
gaussDerivative()
Differentiates a profile using a Gaussian derivative filter kernel. The filter is normalized such that the overall magnitude of the output is independent of the filter size. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Invalid flags are not allowed in this operation.
first, slope
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
Input profile. |
kernelSizeSamples |
INT |
Size of the kernel, must be positive and odd. |
order |
ENUM DifferentiationOrder |
FIRST gives first order derivative and SECOND gives second order derivative. |
| Name | Type | Description |
|---|---|---|
derivativeProfile |
OBJECT Profile |
Output profile, differentiated by the Gaussian derivative filter. |
local derivativeProfile = Profile.gaussDerivative(profile, kernelSizeSamples, order)
getArea()
Returns estimate of the signed area of the measurements in the profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. Signed area: Negative values contribute with negative area. Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.
riemann, integral
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile or vector of profiles. |
| Name | Type | Description |
|---|---|---|
area |
FLOAT |
The estimated area. |
validCount |
INT |
The number of valid measurements per profile. |
local area, validCount = Profile.getArea(profile)
getClosed()
Returns if the closed flag is enabled. If the flag is enabled, the profile is considered closed, meaning that the first measurement follows after the last. This affects the border handling of some operations such as filtering algorithms.
circular, infinite, periodic
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile object. |
| Name | Type | Description |
|---|---|---|
isClosed |
BOOL |
Indicating if the profile is closed. |
local isClosed = Profile.getClosed(profile)
getCoordinate()
Returns the coordinates of the given index or vector of indexes.
location, position, spatial
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile object. |
index |
INT |
The index or vector of indexes. Zero-based indexing. |
| Name | Type | Description |
|---|---|---|
coordinate |
AUTO |
The world coordinate(s), a (vector of) floating point number(s) for 1D coordinates and a (vector of) 2D point(s) for 2D coordinates. Returns nil if any index is out-of-range. |
local coordinate = Profile.getCoordinate(profile, index)
getCoordinateType()
Return the used coordinate representation type. Possible coordinate types: IMPLICIT_1D, EXPLICIT_1D, IMPLICIT_2D, EXPLICIT_2D.
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile object. |
| Name | Type | Description |
|---|---|---|
coordinateType |
ENUM CoordinateType |
The coordinate type. |
coordinateType = Profile.getCoordinateType(profile)
getDistance()
Returns the Euclidian distances between two specified profile elements. Two distances are returned, one along the coordinate axis and one between the two points represented by the (coordinate, value) pairs. For example, if the coordinates represent 2D points, the distances are calculated as follows respectively: coordinage distance: sqrt(dX^2 + dY^2) total distance: sqrt(dX^2 + dY^2 + dValue^2)
euclidian
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile object. |
index1 |
INT |
Index of sample 1 or vector with indices. |
index2 |
INT |
Index of sample 2 or vector with indices.. |
| Name | Type | Description |
|---|---|---|
coordDist |
FLOAT |
Distance in the coordinate dimensions (Euclidean distance). |
totalDist |
FLOAT |
Distance in the value + coordinate dimensions (Euclidean distance). |
local coordDist, totalDist = Profile.getDistance(profile, index1, index2)
getHistogram()
Returns the histogram of the values in a profile or a set of profiles. The bin centers are returned as the coordinates in the result profile. Values outside the bins (minValue,maxValue) are discarded. Valid flags handling: Only the valid measurements are considered in the calculation.
distribution, statistics
| Name | Type | Description |
|---|---|---|
profiles |
CONST_OBJECT Profile |
The source profiles. |
binCount |
INT |
The number of bins to be used in the histogram. If no value is specified the default number of bins (32) is used. |
minValue |
FLOAT |
The minimum value of the histogram. If no value is specified an automatic value based on the minimum value of all profiles will be used. |
maxValue |
FLOAT |
The maximum value of the histogram. If no value is specified an automatic value based on the maximum value of all profiles will be used. |
| Name | Type | Description |
|---|---|---|
histogram |
OBJECT Profile |
Histogram, represented as a profile. The profile coordinates is the center of each histogram bin. |
local histogram = Profile.getHistogram(profiles, binCount, minValue, maxValue)
getIntersectionAngle()
Measures angle between two lines fitted around a given position in the input profile. One line is fitted to samples to the left of the given position and the other to the right using a robust RANSAC least squares fitting. The measured angle is between 0 and 2*PI, and is measured above the profile. Thus, a valley ( \/ ) gives an angle smaller than PI and a peak ( /\ ) an angle larger than PI (if \/ = a then /\ = 2*PI - a). Coordinate system handling: The coordinate are considered in the line fitting operation. The coordinate system of the profile must be 1D. Valid flags handling: Only valid values from the input profiles are used.
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
position |
INT |
Position to estimate lines around expressed as a sample index. |
regionSize |
INT |
Size of region(s), expressed in samples, to the left and right of the given position to use for line fitting. With a scalar input the left and right regions are of equal size. If vector the first value is the size of the left region and the second the size of the right region. |
skipSize |
INT |
Skip samples before the region start to produce a gap to the given position for the line fitting. With a vector input, a different number of samples can be skipped to the left and right respectively. |
iterations |
INT |
Number of iterations in the RANSAC loop in the line fitting. Default value is 200. Can be reduced if there are few or no outliers. |
| Name | Type | Description |
|---|---|---|
angleRad |
FLOAT |
Intersection angle, in radians. |
intersectionPoint |
OBJECT Point |
Intersection point of the lines, expressed as a 2D Point using (coordinate, value) as components. |
leftLine |
OBJECT Profile.Curve |
Left line. |
rightLine |
OBJECT Profile.Curve |
Right line. |
local angleRad, intersectionPoint, leftLine, rightLine = Profile.getIntersectionAngle(profile, position, regionSize, skipSize, iterations)
getMax()
Returns the maximum value of a profile. In addition, the (first) index and the number of valid measurements are also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both maxValue and validCount. Start and stop indices (inclusive) can be used to calculate the maximum on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.
maximum
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile or vector of profiles. |
startIndex |
INT |
Start index of search range. |
stopIndex |
INT |
Stop index of search range. |
| Name | Type | Description |
|---|---|---|
maxValue |
FLOAT |
The maximum value for each input profile. |
index |
INT |
The (first) index at which the maximum value is located. Vector output if a vector of profiles is given as input. |
validCount |
INT |
The number of valid measurements per input profile. |
local maxValue, index, validCount = Profile.getMax(profile)
getMean()
Returns the mean value of a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both meanValue and validCount. Start and stop indices (inclusive) can be used to calculate the mean on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.
statistics, average
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile or vector of profiles. |
startIndex |
INT |
Start index of search range. |
stopIndex |
INT |
Stop index of search range. |
| Name | Type | Description |
|---|---|---|
meanValue |
FLOAT |
The mean value, one value for each profile. |
validCount |
INT |
The number of valid elements per profile. |
local meanValue, validCount = Profile.getMean(profile)
getMedian()
Returns the median value of a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both medianValue and validCount. Start and stop indices (inclusive) can be used to calculate the median on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.
statistics, percentile
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile or vector of profiles. |
startIndex |
INT |
Start index of search range. |
stopIndex |
INT |
Stop index of search range. |
| Name | Type | Description |
|---|---|---|
medianValue |
FLOAT |
The median value, one value for each profile. |
validCount |
INT |
The number of valid measurements per profile. |
local medianValue, validCount = Profile.getMedian(profile)
getMin()
Returns the minimum value of a profile. In addition, the (first) index and the number of valid measurements are also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for both minValue and validCount. Start and stop indices (inclusive) can be used to calculate the minimum on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.
minimum
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile or vector of profiles. |
startIndex |
INT |
Start index of search range. |
stopIndex |
INT |
Stop index of search range. |
| Name | Type | Description |
|---|---|---|
minValue |
FLOAT |
The minimum value for each input profile. |
index |
INT |
The (first) index at which the minimum value is located. Vector output if a vector of profiles is given as input. |
validCount |
INT |
The number of valid measurements per input profile. |
local minValue, index, validCount = Profile.getMin(profile)
getSize()
Returns the number of measurements in the profile.
width, length
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile object. |
| Name | Type | Description |
|---|---|---|
size |
INT |
The number of measurements in the profile. |
local size = Profile.getSize(profile)
getStandardDeviation()
Returns both the mean and standard deviation of the measurements in a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. For empty profiles or profiles without valid data, zero is returned for meanValue, stdDev and validCount. Start and stop indices (inclusive) can be used to calculate the standard deviation on a part of the profile(s). Coordinate system handling: The coordinate representation is not considered in this operation. Valid flags handling: Only the valid measurements are considered in the calculation.
statistics, variance
| Name | Type | Description |
|---|---|---|
profiles |
CONST_OBJECT Profile |
The source profile or vector of profiles. |
startIndex |
INT |
Start index of search range. |
stopIndex |
INT |
Stop index of search range. |
| Name | Type | Description |
|---|---|---|
meanValue |
FLOAT |
The mean value for each profile. |
stdDev |
FLOAT |
The standard deviation (maximum likelihood estimate), for each profile. |
validCount |
INT |
The number of valid measurements per profile. |
local meanValue, stdDev, validCount = Profile.getStandardDeviation(profile)
getSum()
Returns the sum of the measurement of a profile. In addition, the number of valid measurements is also returned. The function is vectorized so that it is possible to operate on a vector of profiles. Zero is returned for profiles without valid data. Start and stop indices (inclusive) can be used to calculate the sum on a part of the profile(s). Valid flags handling: Only the valid measurements are considered in the calculation.
integral, statistics, summation, total
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile or vector of profiles. |
startIndex |
INT |
Start index of search range. |
stopIndex |
INT |
Stop index of search range. |
| Name | Type | Description |
|---|---|---|
sum |
FLOAT |
The sum, one sum for each profile. |
validCount |
INT |
The number of valid measurements per profile. |
local sumValue, validCount = Profile.getSum(profile)
getValidCount()
Get the number of valid elements in a profile or set of profiles, one count for each profile is returned. If valid flags are not used validCount = profile.Size().
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile or profiles. |
| Name | Type | Description |
|---|---|---|
validCount |
INT |
Number of valid elements. |
local validCount = Profile.getValidCount(profile)
getValidFlag()
Returns the valid flag of the measurements at the given index or vector of indexes.
missing data
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile object. |
index |
INT |
The index or vector of indexes. Zero-based indexing. |
| Name | Type | Description |
|---|---|---|
flag |
INT |
The valid flag. 0 means invalid data and non-zero valid data. Returns nil if any index is out-of-range. |
local flag = Profile.getValidFlag(profile, index)
getValidFlagsEnabled()
Checks if global usage of valid flags is enabled. 'False' means that all measurement values are treated as valid regardless of the valid flags vector. 'True' means that the valid flag is regarded for each measurement.
missing data
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile object. |
| Name | Type | Description |
|---|---|---|
validFlagsEnabled |
BOOL |
Indicating if the valid flags are enabled. |
local validFlagsEnabled = Profile.getValidFlagsEnabled(profile)
getValue()
Returns the measurement values of a profile at the provided index or indexes.
sample, element
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile object. |
index |
INT |
The index or vector if indexes to get. Zero-based indexing. |
| Name | Type | Description |
|---|---|---|
value |
FLOAT |
The value(s). Returns nil if any index is out-of-range. |
local value = Profile.getValue(profile, index)
interpolateCoordinate()
Returns coordinate(s) which are linearly interpolated between the two closest indexes in the profile. Coordinate system handling: The function returns 2D Points for profiles with 2D coordinates and floats for profiles with 1D coordinates. Valid flags handling: Valid flags are not considered in this function.
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile. |
indexFloat |
FLOAT |
Index or indexes in floating point precision. Zero-based indexing. |
| Name | Type | Description |
|---|---|---|
coordinate |
AUTO |
The world coordinate(s) as a single value/point or as a vector of values/points. Returns nil if any index is out-of-range. |
local coordinate = Profile.interpolateCoordinate(profile, indexFloat)
load()
Imports a profile from the specified file path. The format is defined by the file extension: .csv: Comma-separated value file .json: JSON (native AppSpace format) .msgpack: MessagePack (native AppSpace format) The csv-file should have numbers written as text, separated by at least one character that is not normally used in numbers (e.g. tab, semicolon, colon, etc.). Only decimal points are accepted, commas are interpreted as delimiters between entries. Values like -1.555e-3 are accepted. Regular spaces are ignored. The first row is taken as values for the profile. If the second row is equal in length, those numbers are interpreted as validity flags (zero means invalid, nonzero means valid). If the third row is equal in length, those numbers are interpreted as coordinates for the samples. Coordinates should be monotonically increasing. Coordinate system handling: If no coordinate row of correct length is present, the coordinate representation will be implicit 1D, starting at 0 with a delta value of 1. If the coordinate row is valid, coordinates will be as given in the third row and of type explicit 1D. Valid flags handling: If no validity row of correct length is present, all measurements are considered as valid. No valid flags vector is created. If the validity mask row is present, the validity flags are set as given in the second row.
import, csv
| Name | Type | Description |
|---|---|---|
filepath |
STRING |
The path and name of the file to load the profile from. |
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The new profile or nil on failure. |
local profile = Profile.load("private/profile.csv")
median()
Smooths a profile using a median filter. Coordinate system handling: The coordinate representation is not considered in this operation. The filter operation wraps around if the isClosed-flag is on. Valid flags handling: Only the valid measurements are considered in the calculation. There is an option to fill in invalid values in the filter operation.
filter, smooth
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
Input profile. |
kernelSize |
INT |
Size of the kernel, must be positive, odd and smaller than the profile length. |
fillInvalid |
BOOL |
Optional flag to also fill in invalid values while filtering. Default is false. |
| Name | Type | Description |
|---|---|---|
smoothProfile |
OBJECT Profile |
Output profile, filtered by the median filter. |
local smoothProfile = Profile.median(profile, kernelSize)
mirror()
Mirrors the values and valid flags in the profile, so that the first sample is placed last and last sample placed first in the output profile. Note that the coordinates are not mirrored.
flip
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Mirrored profile. |
local result = Profile.mirror(profile)
mirrorInplace()
In-place version of mirror that modifies the input profile. See base function for full documentation.
flip
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The source profile and result profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the mirrored profile. |
local result = Profile.mirrorInplace(profile)
multiply()
Multiplies two profiles sample-wise. The two profiles must have the same number of measurements. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.
times
| Name | Type | Description |
|---|---|---|
profile1 |
CONST_OBJECT Profile |
The first source profile. |
profile2 |
CONST_OBJECT Profile |
The second source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The product profile. |
local result = Profile.multiply(profile1, profile2)
multiplyAddConstant()
Multiplies one profile with alpha, thereafter the constant beta is added. If the multiplication underflows/overflows, the result is underflow/overflow, regardless of the addition. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
alpha |
FLOAT |
The constant to multiply with. |
beta |
FLOAT |
The constant to add. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The resulting profile. |
local result = Profile.multiplyAddConstant(profile, alpha, beta)
multiplyAddConstantInplace()
In-place version of the Profile.multiplyAddConstant function that modifies the input profile. See base function for full documentation.
| Name | Type | Description |
|---|---|---|
profile1 |
OBJECT Profile |
The first source profile. This profile is overwritten with the result of the multiplication and sum. |
alpha |
FLOAT |
The constant to multiply with. |
beta |
FLOAT |
The constant to add. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.multiplyAddConstantInplace(profile1, alpha, beta)
multiplyConstant()
Multiplies a profile with a constant. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.
scale
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
constant |
FLOAT |
The constant to multiply the samples with. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The multiplied profile. |
local result = Profile.multiplyConstant(profile, constant)
multiplyConstantInplace()
In-place version of the Profile.multiplyConstant function that modifies the input profile. See base function for full documentation.
scale
| Name | Type | Description |
|---|---|---|
profile1 |
OBJECT Profile |
The first source profile. This profile is overwritten with the result of the multiplication. |
constant |
FLOAT |
The constant to multiply the samples with. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.multiplyConstantInplace(profile1, constant)
multiplyInplace()
In-place version of the Profile.multiply function that modifies the input profile. See base function for full documentation.
times
| Name | Type | Description |
|---|---|---|
profile1 |
OBJECT Profile |
The first source profile. This profile is overwritten with the result of the multiplication. |
profile2 |
CONST_OBJECT Profile |
The second source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.multiplyInplace(profile1, profile2)
pow()
Raises each measurement value to the power of an exponent. Coordinate system handling: The coordinate representation of the input profile is copied to the output profile. Valid flags handling: The valid flags representation of the input profile is copied to the output profile.
exponential, square, squared, power
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
exponent |
FLOAT |
The exponent. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The resulting profile. |
local result = Profile.pow(profile, exponent)
powInplace()
In-place version of the Profile.pow function that modifies the input profile. See base function for full documentation.
exponential, square, squared, power
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The source profile. This profile is overwritten with the result of the pow. |
exponent |
FLOAT |
The exponent. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.powInplace(profile, exponent)
removeValidFlagVector()
Remove the valid flag vector from the profile.
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile object. |
Profile.removeValidFlagVector(profile)
resize()
Samples the profile using the given number of samples and outputs these as a new profile. Linear interpolation is used. Both input and output profiles must have at least two samples. The new samples are placed equidistantly. For explicit 2D coordinates, the distance along the coordinate polygon is used. All input samples must have unique positions. Explicit 1D coordinates in the input profile must be strictly monotonic. Coordinate system handling: Implicit 1D coordinates are used for the output when the input coordinates are 1D (implicit or explicit). For 2D coordinates, the output coordinate type is the same as the input coordinate type. The closedness of the profile is taken into account when placing the new samples in all cases except for explicit 1D coordinates, where the wrap-around point is undefined. Valid flags handling: Valid flags are respected. Any output sample where at least one of the input samples used for interpolation is invalid, is marked as invalid.
decimate, equidistant, interpolate, scale, subsample, resample
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile to resize. |
newSize |
INT |
The desired size of the new profile in samples. |
| Name | Type | Description |
|---|---|---|
newProfile |
OBJECT Profile |
The new profile, or nil on error. |
local newProfile = Profile.resize(profile, newSize)
resizeScale()
Samples the profile using the given scale factor of samples in relation to the number of samples in the input profile. E.g. a factor 2 generates twice as many samples in the new profile. Linear interpolation is used. Both input and output profiles must have at least two samples. The new samples are placed equidistantly. For explicit 2D coordinates, the distance along the coordinate polygon is used. All input samples must have unique positions. Explicit 1D coordinates in the input profile must be strictly monotonic. Coordinate system handling: Implicit 1D coordinates are used for the output when the input coordinates are 1D (implicit or explicit). For 2D coordinates, the output coordinate type is the same as the input coordinate type. The closedness of the profile is taken into account when placing the new samples in all cases except for explicit 1D coordinates, where the wrap-around point is undefined. Valid flags handling: Valid flags are respected. Any output sample where at least one of the input samples used for interpolation is invalid, is marked as invalid.
decimate, equidistant, interpolate, scale, subsample, resample
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile to resize. |
factor |
FLOAT |
Resize factor, e.g, 0.5 or 2.0. |
| Name | Type | Description |
|---|---|---|
newProfile |
OBJECT Profile |
The new profile, or nil on error. |
local newProfile = Profile.resizeScale(profile, factor)
rotate()
Rotates a profile in the value-coordinate plane. Only 1D coordinates are supported. Result is always in EXPLICIT_1D coordinates.
transform
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
rotationRad |
FLOAT |
Rotation in radians. A positive rotation is in the counterclockwise direction. |
coordinateOrigin |
FLOAT |
Optional origin of rotation in the coordinate dimension. Default: 0.0 |
valueOrigin |
FLOAT |
Optional origin of rotation in the value dimension. Default: 0.0 |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Rotated profile. EXPLICIT_1D coordinates. |
local result = Profile.rotate(profile, rotationRad, coordinateOrigin, valueOrigin)
rotateInplace()
In-place version of rotate. Only 1D coordinates are supported. Result is always in EXPLICIT_1D coordinates.
transform
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile to rotate. This profile is overwritten with the result of the rotation. |
rotationRad |
FLOAT |
Rotation in radians. A positive rotation is in the counter clockwise direction. |
coordinateOrigin |
FLOAT |
Optional origin of rotation in the coordinate dimension. Default: 0.0 |
valueOrigin |
FLOAT |
Optional origin of rotation in the value dimension. Default: 0.0 |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the rotated profile. EXPLICIT_1D coordinates. |
local result = Profile.rotateInplace(profile, rotationRad, coordinateOrigin, valueOrigin)
save()
Writes a profile to the specified file path. Overwrites the file if it already exists. The format is defined by the file extension: .csv: Comma-separated value file, using a semicolon as separator. .json: JSON (native AppSpace format) .msgpack: MessagePack (native AppSpace format) For the csv-file format the first line contains the profile values. If the validity flags are active, the second line contains the flags (0 means invalid, 1 means valid). If coordinates are explicit 1D, the third line contains the coordinate of each sample. Coordinate system handling: Only 1D coordinates are supported. Implicit coordinates are not written to the file. Explicit coordinates are written to the third line in the output file. Valid flags handling: If the validity flags are active, those are written to the second line in the output file.
export, csv
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile to store. |
filepath |
STRING |
The path and name of the file to write the profile to. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True on success, false on write error, nil if the call was malformed. |
local success = Profile.save(profile, "private/profile.csv")
setClosed()
Sets the closed flag. If the flag is enabled, the profile is considered closed, meaning that the first measurement follows after the last. This affects the border handling of some algorithms. This operation does not affect any values, coordinates of measurements or valid flags.
circular, infinite, periodic
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile object. |
setClosed |
BOOL |
Marking the profile as closed (true) or as open (false). |
Profile.setClosed(profile, true)
setCoordinate()
Sets the coordinates of the given index or indexes. The dimensionality of the new coordinates must match those of the profile, e.g. only 2D coordinates can be set in a profile already using 2D coordinates. If the coordinate representation of the profile is implicit, it is silently converted to an explicit representation before updating coordinates. Use setImplicitCoordinates to setup an implicit coordinate system.
location, position, spatial
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile object. |
index |
INT |
The index or vector of indexes. Zero-based indexing. Out-of-range indexes are ignored. |
coordinate |
CONST_AUTO |
The world coordinates, a (vector of) floating point number(s) for 1D coordinates and a (vector of) 2D point(s) for 2D coordinates. The vector must be of the same length as the index vector. |
Profile.setCoordinate(profile, index, coordinate)
setImplicitCoordinates()
Sets the coordinates of the profile to implicit type (the coordinates of the first sample and a difference between samples). Provide two floating point numbers to set 1D coordinates, or two 2D points to set 2D coordinates. Use setCoordinate to set explicit coordinates of specific samples.
location, position, spatial
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile object. |
start |
CONST_AUTO |
The coordinates of the first sample, a scalar value or 2D Point. |
delta |
CONST_AUTO |
The difference in position of each two consecutive samples, a scalar value or 2D Point. |
Profile.setImplicitCoordinates(profile, start, delta)
setValidFlag()
Set the valid flags of a profile at the given index or vector of indexes. Sets the flags in the input profile (in-place).
missing data
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile object. |
index |
INT |
The index or vector of indexes. Zero-based indexing. Out-of-range indexes are ignored. |
flag |
INT |
The valid flag to set to the indices. 0 means invalid and non-zero means valid. |
Profile.setValidFlag(profile, index, flag)
setValidFlagRange()
Set a range of valid flags in the input profile (inplace). Sets all valid flags between startIndex and stopIndex to the specified flag. If stopIndex is omitted all flags from startIndex to the end of the profile is set.
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile object. |
flag |
INT |
The valid flag or vector of valid flags, to set to the indices. 0 means invalid and non-zero means valid. |
startIndex |
INT |
Start index or vector of start indices. Zero-based indexing. |
stopIndex |
INT |
Stop index or vector of stop indices. Zero-based indexing. Optional. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
result = Profile.setValidFlagRange(profile, flag, startIndex, stopIndex)
setValidFlagsEnabled()
Enables or disables the individual valid flag of each measurement. 'False' means that all measurement values are treated as valid regardless of the valid flags set. 'True' means that the valid flag is regarded for each measurement. If the flags are enabled and the profile did not contain a valid flags vector, the vector is generated.
missing data
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile object. |
validFlagsEnabled |
BOOL |
Activating or deactivating the usage of the valid data flags vector. |
Profile.setValidFlagsEnabled(profile, validFlagsEnabled)
setValue()
Set a measurement value in a profile at one or multiple given position(s). Out-of-range indexes are ignored.
sample, element
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile object. |
index |
INT |
The index or indexes to set. Zero-based indexing. |
value |
FLOAT |
The measurement value to set. |
Profile.setValue(profile, index, value)
shrink()
Sets all values within a threshold of a given level to that level. For example, with the default level zero, all values within +/- a threshold are set to zero. In denoising context, this is known as a shrinkage operation or hard thresholding. Coordinate system handling: The coordinate representation is copied to the output profile. Valid flags handling: Valid flags are copied to the output.
denoise, hard thresholding, soft thresholding, clamp
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The input profile. |
threshold |
FLOAT |
Values within this distance of level is set to level. |
level |
FLOAT |
The level to shrink around, default is zero. |
| Name | Type | Description |
|---|---|---|
newProfile |
OBJECT Profile |
The new profile, or nil on error. |
local newProfile = Profile.shrink(profile, threshold, level)
shrinkInplace()
Inplace version of the shrink function that modifies the input profile. See the base function for full documentation.
denoise, hard thresholding, soft thresholding, clamp
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile. |
threshold |
FLOAT |
Values within this distance of level is set to level. |
level |
FLOAT |
The level to shrink around, default is zero. |
Profile.shrinkInplace(profile, threshold, level)
sort()
Sort a profile with respect to sample values or coordinates. The validity flags and explicit coordinates follow the samples while sorting. Implicit coordinates are unaffected by sorting. When sorting by coordinates, explicit 1D coordinates must be used. A stable sorting algorithm is used, such that samples with equal value do not change order internally. Invalid values are sorted as if marked as valid, but their invalidity flag is kept.
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
ascending |
BOOL |
True if profile is to be sorted in ascending order. Optional, default is true. |
key |
ENUM SortKey |
Indicates if samples are to be sorted by value or by coordinate. Optional, default is sorting by value. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Sorted profile. |
index |
INT |
Vector of indices indicating the effect of the sorting operation. The first entry indicates what sample in the input that ended up first in the output. Indices are zero-based. |
local result, index = Profile.sort(profile, ascending, key)
subtract()
Subtracts the second profile from the first, sample-wise. The two profiles must have the same number of samples. Coordinate system handling: The coordinate representation of the first input profile is copied to the output profile. Valid flags handling: Both input profiles must have a valid measurement to produce a valid output for an index.
minus
| Name | Type | Description |
|---|---|---|
profile1 |
CONST_OBJECT Profile |
The first source profile. |
profile2 |
CONST_OBJECT Profile |
The second source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
The difference profile. |
local result = Profile.subtract(profile1, profile2)
subtractInplace()
In-place version of the Profile.subtract function that modifies the input profile. See base function for full documentation.
minus
| Name | Type | Description |
|---|---|---|
profile1 |
OBJECT Profile |
The first source profile. This profile is overwritten with the result of the difference. |
profile2 |
CONST_OBJECT Profile |
The second source profile. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the result profile. |
local result = Profile.subtractInplace(profile1, profile2)
threshold()
Return the indices of all valid profile values between the upper and lower threshold. Any threshold can be left out, in which case it has no influence on the selection. Coordinate system handling: The positions of the samples do not influence the function. Missing data handling: Only valid samples are included in the output.
region, segmentation
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
Input profile. |
lowerThreshold |
FLOAT |
Lower threshold. Optional, default is no lower threshold (no lower limit on sample value). |
upperThreshold |
FLOAT |
Upper threshold. Optional, default is no upper threshold (no upper limit on sample value). |
| Name | Type | Description |
|---|---|---|
indices |
INT |
Zero-based indices to all valid samples between the upper and lower threshold. |
local indices = Profile.threshold(profile, lowerThreshold, upperThreshold)
toImage()
Convert a vector of profiles to an image, stacked vertically. The coordinates in the profiles are not used. Valid flags handling: If any of the input profiles has valid flags enabled, the resulting image will have missing data enabled. In that case, any pixel corresponding to an invalid sample in the profile will be stored as missing data in the image.
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile or vector of profiles. |
type |
ENUM ImageType |
The pixel type of the resulting image. |
pixelSizeZ |
FLOAT |
The pixel size in the z-dimension in world coordinates, e.g., the number of millimeters each pixel value integer increment corresponds to. (Default value: 1.0). By selecting 0.0 the scale will be automatically selected. |
minZ |
FLOAT |
The smallest value that is represented in the output image. (Default value: 0.0). |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Image |
Resulting image. |
local result = Profile.toImage(profile, type, pixelSizeZ, minZ)
toString()
Gets a user-friendly string description of the profile.
description, help, print
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile object. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the profile. |
local str = Profile.toString(profile)
toVector()
Returns the measurement values, coordinates and valid flags of a profile as vectors. Coordinate system handling: A coordinate vector of the same length as the measurement vector is returned. If the coordinate representation is of implicit type, the vector is calculated. Valid flags handling: If the valid flags are disabled, no flags are returned.
convert
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The profile. |
| Name | Type | Description |
|---|---|---|
values |
FLOAT |
The vector of measurement values, or nil if the profile is not valid. |
coordinates |
CONST_AUTO |
Vector of world coordinates (floats or 2D points), nor nil if the profile is not valid. |
flags |
INT |
Vector of valid data flags, or nil if the flags are not enabled. |
local values, coordinates, flags = Profile.toVector(profile)
translate()
Translates a profile in the coordinate dimension and/or in the value dimension. Only 1D coordinates are supported.
move, shift, transform
| Name | Type | Description |
|---|---|---|
profile |
CONST_OBJECT Profile |
The source profile. |
coordinateTranslation |
FLOAT |
Translation of coordinates. |
valueTranslation |
FLOAT |
Translation of values. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Translated profile. |
local result = Profile.translate(profile, coordinateTranslation, valueTranslation)
translateInplace()
In-place version of translate, see base function for full documentation.
move, shift, transform
| Name | Type | Description |
|---|---|---|
profile |
OBJECT Profile |
The profile to translate. This profile is overwritten with the translated profile. |
coordinateTranslation |
FLOAT |
Translation of coordinates. |
valueTranslation |
FLOAT |
Translation of values. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile |
Reference to the translated profile. |
local result = Profile.translateInplace(profile, coordinateTranslation, valueTranslation)
Profile.Curve
A data type for representing parametric curves and functions such as polynomial and exponential functions. Different families of functions are available.
Keywords
analytic, exponential, fitting, function, gauss, line, parametric, trend, polynomial
See also
Overview
Functions
clone()
Create an independent copy of this curve.
copy
| Name | Type | Description |
|---|---|---|
inputCurve |
CONST_OBJECT Profile.Curve |
The curve to clone. |
| Name | Type | Description |
|---|---|---|
outputCurve |
OBJECT Profile.Curve |
The new copy. |
outputCurve = Profile.Curve.clone(inputCurve)
createExponential()
Create an exponential curve. f(x) = scale*exp(exponent*x) + offset.
| Name | Type | Description |
|---|---|---|
scale |
FLOAT |
Linear scaling of the curve. |
exponent |
FLOAT |
Exponent. |
offset |
FLOAT |
Constant offset of the curve. |
| Name | Type | Description |
|---|---|---|
expCurve |
OBJECT Profile.Curve |
The created exponential curve. |
expCurve = Profile.Curve.createExponential(scale, exponent, offset)
createGaussian()
Create a Gaussian curve. f(x) = scale*exp(-x-mean)^2) / (2*sigma^2 + offset.
| Name | Type | Description |
|---|---|---|
scale |
FLOAT |
Linear scaling of the curve. |
mean |
FLOAT |
Mean (symmetry axis of generated function). |
sigma |
FLOAT |
Standard deviation (width of lobe). |
offset |
FLOAT |
Constant offset of the curve. |
| Name | Type | Description |
|---|---|---|
gaussCurve |
OBJECT Profile.Curve |
The created Gaussian curve. |
gaussCurve = Profile.Curve.createGaussian(scale, mean, sigma, offset)
createLine()
Create a line f(x) = offset + slope*x with the specified offset and slope. This is equivalent to creating a first order polynomial.
| Name | Type | Description |
|---|---|---|
offset |
FLOAT |
Offset of line, value at x = 0. |
slope |
FLOAT |
Slope of line, dy/dx. |
| Name | Type | Description |
|---|---|---|
line |
OBJECT Profile.Curve |
The created line. |
line = Profile.Curve.createLine(offset, slope)
createPolynomial()
Create a polynomial curve with the specified coefficients. The first coefficient is the constant term, the second is for the linear term and so on.
| Name | Type | Description |
|---|---|---|
coefficients |
FLOAT |
Coefficients a, b, c, … in a + b*x + c*x^2 + … |
| Name | Type | Description |
|---|---|---|
polyCurve |
OBJECT Profile.Curve |
The created polynomial curve. |
polyCurve = Profile.Curve.createPolynomial(coefficients)
getDerivative()
Return the derivative of the curve if it can be expressed by any available curve type.
| Name | Type | Description |
|---|---|---|
curve |
CONST_OBJECT Profile.Curve |
The curve to take the derivative of. |
| Name | Type | Description |
|---|---|---|
derivativeCurve |
OBJECT Profile.Curve |
The derivative of the curve. |
derivativeCurve = Profile.Curve.getDerivative(curve)
getExponentialParameters()
Returns the parameters of an exponential curve, f(x) = scale*exp(exponent*x) + offset.
| Name | Type | Description |
|---|---|---|
expCurve |
CONST_OBJECT Profile.Curve |
The exponential curve. |
| Name | Type | Description |
|---|---|---|
scale |
FLOAT |
Linear scaling of the curve. |
exponent |
FLOAT |
Exponent. |
offset |
FLOAT |
Constant offset of the curve. |
scale, exponent, offset = Profile.Curve.getExponentialParameters(expCurve)
getGaussianParameters()
Returns the parameters of a Gaussian curve, f(x) = scale*exp(-x-mean)^2) / (2*sigma^2 + offset.
| Name | Type | Description |
|---|---|---|
gaussCurve |
CONST_OBJECT Profile.Curve |
The Gaussian curve. |
| Name | Type | Description |
|---|---|---|
scale |
FLOAT |
Linear scaling of the curve. |
mean |
FLOAT |
Mean (symmetry axis of generated function). |
sigma |
FLOAT |
Standard deviation (width of lobe). |
offset |
FLOAT |
Constant offset of the curve. |
scale, mean, sigma, offset = Profile.Curve.getGaussianParameters(gaussCurve)
getLineParameters()
Returns the offset and slope of a line.
| Name | Type | Description |
|---|---|---|
line |
CONST_OBJECT Profile.Curve |
The line. |
| Name | Type | Description |
|---|---|---|
offset |
FLOAT |
Offset of line, value at x = 0. |
slope |
FLOAT |
Slope of line, dy/dx. |
offset, slope = Profile.Curve.getLineParameters(line)
getPolynomialParameters()
Returns the coefficients of a polynomial curve. The first coefficient is the constant term, the second is for the linear term and so on.
| Name | Type | Description |
|---|---|---|
polyCurve |
CONST_OBJECT Profile.Curve |
The polynomial curve. |
| Name | Type | Description |
|---|---|---|
coefficients |
FLOAT |
Coefficients a, b, c, … in a + b*x + c*x^2 + … |
coefficients = Profile.Curve.getPolynomialParameters(polyCurve)
getType()
Return the type of function that represents the curve.
| Name | Type | Description |
|---|---|---|
curve |
CONST_OBJECT Profile.Curve |
The curve to check. |
| Name | Type | Description |
|---|---|---|
curveType |
ENUM CurveType |
The curve type. |
curveType = Profile.Curve.getType(curve)
scale()
Scales a curve in the coordinate dimension and/or in the value dimension by recalculating curve parameters, centered around the origin. A nil value indicates unit scaling in the corresponding dimension.
multiply, resize, transform
| Name | Type | Description |
|---|---|---|
curve |
CONST_OBJECT Profile.Curve |
The source curve. |
coordinateScale |
FLOAT |
Scale factor of coordinates. |
valueScale |
FLOAT |
Scale factor of values. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile.Curve |
Scaled curve. |
local result = Profile.Curve.scale(curve, coordinateScale, valueScale)
scaleInplace()
In-place version of scale, see base function for full documentation.
multiply, resize, transform
| Name | Type | Description |
|---|---|---|
curve |
OBJECT Profile.Curve |
The curve to scale and the scaled curve. |
coordinateScale |
FLOAT |
Scale factor of coordinates. |
valueScale |
FLOAT |
Scale factor of values. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile.Curve |
Reference to the scaled profile. |
local result = Profile.Curve.scaleInplace(curve, coordinateScale, valueScale)
toProfile()
Evaluate the curve at all points in the reference profile and return as a new profile. The reference profile must have 1D sampling coordinates. For a smoother plot, extra samples may be inserted between the samples of the reference profile. This is controlled by the optional parameter extraSamples.
| Name | Type | Description |
|---|---|---|
curve |
CONST_OBJECT Profile.Curve |
Input curve. |
referenceProfile |
CONST_OBJECT Profile |
Reference profile. |
extraSamples |
INT |
This many samples are inserted in the output profile between each two samples of the reference profile. Default is zero. |
| Name | Type | Description |
|---|---|---|
curveProfile |
OBJECT Profile |
The sampled curve as a profile. |
curveProfile = Profile.Curve.toProfile(curve, referenceProfile, extraSamples)
toString()
Get a human-readable string describing the curve.
print, description
| Name | Type | Description |
|---|---|---|
curve |
CONST_OBJECT Profile.Curve |
Input curve. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
String description of the curve. |
print(Profile.Curve.toString(curve))
translate()
Translates a curve in the coordinate dimension and/or in the value dimension by recalculating curve parameters. A nil value indicates no translation in the corresponding dimension.
move, shift, transform
| Name | Type | Description |
|---|---|---|
curve |
CONST_OBJECT Profile.Curve |
The source curve. |
coordinateTranslation |
FLOAT |
Translation of coordinates. |
valueTranslation |
FLOAT |
Translation of values. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile.Curve |
Translated curve. |
local result = Profile.Curve.translate(curve, coordinateTranslation, valueTranslation)
translateInplace()
In-place version of translate, see base function for full documentation.
move, shift, transform
| Name | Type | Description |
|---|---|---|
curve |
OBJECT Profile.Curve |
The curve to translate and the translated curve. |
coordinateTranslation |
FLOAT |
Translation of coordinates. |
valueTranslation |
FLOAT |
Translation of values. |
| Name | Type | Description |
|---|---|---|
result |
OBJECT Profile.Curve |
Reference to the translated profile. |
local result = Profile.Curve.translateInplace(curve, coordinateTranslation, valueTranslation)
Profile.CurveFitter
For fitting parametric curves and functions to measurements stored in a profile object. Both ordinary least squares fitting (default) and robust fitting using RANSAC are possible.
Keywords
curve, function, least squares, ransac, trend, fitting
See also
Overview
Functions
create()
Create a curve fitter with default settings.
| Name | Type | Description |
|---|---|---|
curveFitter |
HANDLE |
Created curve fitter. |
curveFitter = Profile.CurveFitter.create()
fitExponential()
Fit an exponential curve to the valid points in a profile.
| Name | Type | Description |
|---|---|---|
curveFitter |
HANDLE |
Curve fitter to use. |
inputProfile |
OBJECT Profile |
The profile to fit the curve to. |
| Name | Type | Description |
|---|---|---|
expCurve |
OBJECT Profile.Curve |
The fitted exponential curve, or nil if fitting failed. |
expCurve = Profile.CurveFitter.fitExponential(curveFitter, inputProfile)
fitGaussian()
Fit a Gaussian curve to the valid points in a profile. Fitting a Gaussian is quite sensitive to noise and degenerate cases, where the points do not come from a Gaussian function. Using RANSAC robust fitting is recommended as it is much less likely to fail.
| Name | Type | Description |
|---|---|---|
curveFitter |
HANDLE |
Curve fitter to use. |
inputProfile |
OBJECT Profile |
The profile to fit the curve to. |
| Name | Type | Description |
|---|---|---|
gaussCurve |
OBJECT Profile.Curve |
The fitted Gaussian curve, or nil if fitting failed. |
gaussCurve = Profile.CurveFitter.fitGaussian(curveFitter, inputProfile)
fitLine()
Fit a line to the valid points in a profile. Equivalent to fitting a first order polynomial. The coordinate system of the profile must be 1D.
| Name | Type | Description |
|---|---|---|
curveFitter |
HANDLE |
Curve fitter to use. |
inputProfile |
OBJECT Profile |
The profile to fit the curve to. |
| Name | Type | Description |
|---|---|---|
line |
OBJECT Profile.Curve |
The fitted line. |
line = Profile.CurveFitter.fitLine(curveFitter, inputProfile)
fitPolynomial()
Fit a polynomial curve to the valid points in a profile. Set the order parameter to zero for a constant function, one for a line, two for a quadratic function and so on. The coordinate system of the profile must be 1D.
| Name | Type | Description |
|---|---|---|
curveFitter |
HANDLE |
Curve fitter to use. |
inputProfile |
OBJECT Profile |
The profile to fit the curve to. |
order |
INT |
Order of the polynomial to fit. |
| Name | Type | Description |
|---|---|---|
polyCurve |
OBJECT Profile.Curve |
The fitted polynomial curve, or nil if fitting failed. |
polyCurve = Profile.CurveFitter.fitPolynomial(curveFitter, inputProfile, order)
getPoints()
Get the edge points used in the last call to any of the fitting functions. Intended for visualization, parameter tuning and debugging. Two lists are returned, the first contains all points that were used to fit the final curve. The second list contains all valid points in the profile not used for fitting the shape. For the least squares method, all points are always in the first list.
| Name | Type | Description |
|---|---|---|
curveFitter |
HANDLE |
Curve fitter to use. |
| Name | Type | Description |
|---|---|---|
inlierPoints |
OBJECT Point |
Points used for the final fitting of the curve, a subset of the valid points in the profile. |
outlierPoints |
OBJECT Point |
Points not used for the final fitting, the remainder of the valid points. |
inlierPoints, outlierPoints = Profile.CurveFitter.getPoints(curveFitter)
getResiduals()
Get fitting information from the last successful curve fit. Values are related to the inliers as can be obtained from getPoints.
| Name | Type | Description |
|---|---|---|
curveFitter |
HANDLE |
Curve fitter to use. |
| Name | Type | Description |
|---|---|---|
rmsError |
FLOAT |
The root mean squared error among the inliers. |
inlierRatio |
FLOAT |
Ratio of inlier points to the total number of points, between 0 and 1. |
inlierResiduals |
FLOAT |
Signed residuals for all inliers, the difference between the curve value and the profile value at each position. |
outlierResiduals |
FLOAT |
Signed residuals for all outliers, the difference between the curve value and the profile value at each position. |
rmsError, inlierRatio, inlierResiduals, outlierResiduals = Profile.CurveFitter.getResiduals(curveFitter)
setFitMode()
Set the fitting mode. The following modes are supported: - LEASTSQUARES uses all points. This is fast and easy, but can produce poor results if there are points that do not belong to the curve to be fitted (default). - RANSAC is a robust method with outlier rejection. Using this method, outlier points can be ignored. This mode requires an outlier margin to be set by setOutlierMargin. The number of iterations can be set by setIterations.
ransac, robust, least squares
| Name | Type | Description |
|---|---|---|
curveFitter |
HANDLE |
Curve fitter to use. |
fitMode |
Fitting mode to use. |
Profile.CurveFitter.setFitMode(curveFitter, fitMode)
setIterations()
Set the maximum number of iterations in the fitting step. A higher value makes the fitting more accurate, but consumes more computation time. The default is 1000 iterations.
| Name | Type | Description |
|---|---|---|
curveFitter |
HANDLE |
Curve fitter to use. |
iterations |
INT |
Number of iterations. |
Profile.CurveFitter.setIterations(curveFitter, iterations)
setOutlierMargin()
Set the outlier margin when using RANSAC robust fitting mode. The interpretation of the margin parameter depends on the fitting mode parameter: - RANK: the outlier margin is interpreted as a rank measure, defining the rate of points to include. In this case, the margin must be in the range (0.0, 1.0). A rank margin of 0.7 means that only the best fitting 70% of all points will be included, and the rest ignored. - ABSOLUTE: the outlier margin is defined in absolute world units. Any points further away from the fitted curve than this margin will be ignored. In general a larger value means that more points are included in the fitting, which can improve the accuracy as long as all included points are valid. A smaller value makes the algorithm reject more points, which can increases robustness against single erroneous points. The default is an RANK margin of 0.5.
| Name | Type | Description |
|---|---|---|
curveFitter |
HANDLE |
Curve fitter to use. |
margin |
FLOAT |
Outlier margin, expressed in world coordinate units or as a rank measure, depending on the marginType. |
marginType |
Outlier margin type. |
Profile.CurveFitter.setOutlierMargin(curveFitter, margin, marginType)
toString()
Get a human-readable string describing the curve fitter.
print, description
| Name | Type | Description |
|---|---|---|
curve |
CONST_OBJECT Profile.CurveFitter |
Input curve fitter. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
String description of the curve. |
print(Profile.CurveFitter.toString(curve))
Profile.Log
Object for incremental logging and statistics of measurements, typically in form of timeseries. Measurements are added one-by-one and statistical properties such as mean, standard deviation, min, max and histogram are updated incrementally. Thus, statistics over infinitely long timeseries can be recorded. There is an option to keep a vector of the most recently added values, for example for plotting reasons. There is also an option to maintain vectors of historic statistics (mean, min, max, std) over time intervals that is dynamically compressed (downsampled) when the vectors get full, so as to be able to calculate statistics over intervals in very long timeseries. Some properties are off by default, such as histogram updating and recent and historic value logging. These options need to be enabled explicitly using the dedicated functions for this, e.g., enableHistogram(). It is possible to save and load Profile.Log instances using the Object.save() and Object.load() functions.
Keywords
analytics, average, histogram, historic, incremental, infinite, logging, mean, record, standard deviation, std, time series, timeseries, statistics
Overview
Functions
addValue()
Add value(s). Values can be added one-by-one, in vector form to add several values at once, or in Profile form.
| Name | Type | Description |
|---|---|---|
log |
OBJECT [API:DataFormat:] |
The log object. |
value |
CONST_AUTO |
Value(s) to add. Can be a single float, a vector of floats, or a Profile object. |
coordinate |
CONST_AUTO |
Optional coordinate of the added value(s), length and type must match the value input. |
create()
Create new Log object
| Name | Type | Description |
|---|---|---|
log |
OBJECT Profile.Log |
The Log object. |
enableHistogram()
Enables the histogram feature to incrementally maintain a histogram of all logged values.
| Name | Type | Description |
|---|---|---|
log |
OBJECT [API:DataFormat:] |
The log object. |
minValue |
FLOAT |
Center coordinate of the lowest bin. |
maxValue |
FLOAT |
Center coordinate of the highest bin. |
binsCount |
INT |
Number of bins. |
enableHistoricStatistics()
Enables the historic statistics feature. Vectors of historic statistics (mean, max, min, std) over time periods are maintained. When the vectors gets full they are compressed (downsampled) a factor 2, and thus the time period represented also increases a factor 2. With this feature one can gather statistics over intervals in very long time series.
| Name | Type | Description |
|---|---|---|
log |
OBJECT [API:DataFormat:] |
The log object. |
periodCount |
INT |
Number of periods to keep. This is also the maximum size of the periods. Must be equal or larger than 10. |
enableRecentValues()
Enables storage of recent values. The size of the vector to maintain needs to be specified.
| Name | Type | Description |
|---|---|---|
log |
OBJECT [API:DataFormat:] |
The log object. |
count |
INT |
The number of stored values. |
getCount()
Get total number of values added to the log.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
count |
INT |
Number of added values. |
getHistogram()
Get the histogram represented as a Profile object. The histogram feature must be enabled.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
recent |
OBJECT Profile |
Histogram with the frequency in the values and bin centers as coordinates. |
getHistoricMax()
Get the maximum of the values in each historic period.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
max |
OBJECT Profile |
Profile with the maximum of the values in the periods. |
getHistoricMean()
Get the mean of the values in each historic period.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
mean |
OBJECT Profile |
Profile with the mean of the values in the periods. |
getHistoricMin()
Get the minimum of the values in each historic period.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
min |
OBJECT Profile |
Profile with the minimum of the values in the periods. |
getHistoricPeriod()
Get number of values in each historic period.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
count |
INT |
Number of stored values per historic period. |
getHistoricStdDev()
Get the standard deviation in each historic period.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
stddev |
OBJECT Profile |
Profile with the standard deviations of the values in the periods. |
getMax()
Get the minimum value and its coordinate over all values added to the log.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
max |
FLOAT |
Maximum value. |
coord |
FLOAT |
Coordinate of maximum value. |
getMean()
Get the mean/average over all values added to the log.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
mean |
FLOAT |
Mean value. |
getMin()
Get the minimum value and its coordinate over all values added to the log.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
min |
FLOAT |
Minimum value. |
coord |
FLOAT |
Coordinate of minumum value. |
getRecentValues()
Get the vector of recent values as a Profile object. Recent values must be enabled.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
recent |
OBJECT Profile |
Profile with the latest values and coordinates. |
getStdDev()
Get the standard deviation over all values added to the log.
| Name | Type | Description |
|---|---|---|
log |
CONST_OBJECT [API:DataFormat:] |
The log object. |
| Name | Type | Description |
|---|---|---|
stddev |
FLOAT |
Standard deviation. |
toString()
Get a string describing the log.
print, description
| Name | Type | Description |
|---|---|---|
curve |
CONST_OBJECT Profile.Log |
Input log. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
String description of the log. |
print(Profile.Log.toString(curve))
Profile.Matching
Functions for matching and locating patterns in profiles based on different shape models such as sample pattern models.
Keywords
detection, feature, pattern, localization
Profile.Matching.PatternMatcher
Finds patterns in a profile based on template matching. Teach a pattern from a reference profile and call match to find the location of the same shape in a live profile.
Functions
create()
Creates a new matcher for 1D pattern localization in profiles.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The new instance. |
locator = Profile.Matching.PatternMatcher.create()
getAllFoundMatches()
Get vector with all found matches sorted with descending score. A match is a local maximum in the comparison mode evaluation.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
| Name | Type | Description |
|---|---|---|
positions |
FLOAT |
Positions (indices) of found matches. |
scores |
FLOAT |
scores. |
positions, scores = Profile.Matching.PatternMatcher.getAllFoundMatches(locator)
match()
Finds a pattern in a live profile by matching with the teach model. A teach call must be made first. The output is the position (index) of the best found match, with the origin for the template in the first element. Only one instance of a pattern is returned, the one with the strongest match score. However, after a match call, a vector of all match candidates can be obtained using the getAllFoundMatches function. A match score in the range [0.0, 1.0] is returned indicating the score strength. Depending on the comparison mode (selected in teach call), the score is calculated as follows: SAD: The best (lowest) SAD_min difference is found. The score is calculated as max(1.0 - SAD_min/(max_value - min_value), 0.0), where max value and min_value are the maximum and minimum values within the teach profile. This gives a score value that is 1.0 if the teach and live are identical, and 0.0 if for example all samples in the live profile deviates with at least the teach range. XCORRNORM: The best (highest) correlation coefficient XCORRNORM_max is found. The score is calculated as max(XCORRNORM_max, 0.0) to give as score 1.0 if the teach and match profiles correlate perfectly. Coordinate system handling: The coordinates are not considered in this function. Invalid flag usage: Invalid samples are excluded from the matching but can affect the score measure.
locate, find
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The matcher instance to use. |
liveProfile |
CONST_OBJECT Profile |
The live profile to find the shape in. |
| Name | Type | Description |
|---|---|---|
position |
FLOAT |
Position (index) of the start of detected pattern in the live profile. Nil is returned if the match process failed. |
matchScore |
FLOAT |
A score between 0.0 and 1.0 for the best detected pattern. High score means good match. |
position, matchScore = Profile.Matching.PatternMatcher.match(locator, liveProfile)
setMaximumInvalidValues()
Set maximum number of invalid samples in the live profile, which overlaps the teach profile. Thus, matches where the teach profile overlaps with too many invalid samples in the live profile are discarded. The default value if this parameter is to allow any number of invalid values.
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
maxInvalidValues |
INT |
Maximum number of invalid samples. |
Profile.Matching.PatternMatcher.setMaximumInvalidValues(locator, maxInvalidValues)
teach()
Teaches a pattern model from a template profile. The template profile is typically shorter than the profile later used for matching in, e.g., it is a cropped version of a reference profile containing just the pattern of interest. Samples can be excluded from the teach model by setting the valid flags of the corresponding samples to invalid. Note that the teach profile must contain atleast 5 valid samples. There are two modes later used in the match call to determine how the teach pattern is compared to a profile to match in: SAD: Sum of absolute differences. A match score is calculated based on the sum of the absolute differences between the teach profile and the match profile. XCORRNORM: Cross correlation with normalization. A match score is calculated based on a cross-correlation operation. This mode is insensitive to different scalings and mean levels between the teach and match profiles.
template, pattern
| Name | Type | Description |
|---|---|---|
locator |
HANDLE |
The instance to use. |
teachProfile |
CONST_OBJECT Profile |
The teach profile. |
comparisonMode |
ENUM ComparisonMode |
Comparison method XCORRNORM or SAD. Default: XCORRNORM. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if teach succeeded. |
success = Profile.Matching.PatternMatcher.teach(locator, teachProfile, matchMode)
toString()
Get a human-readable string describing the pattern matcher.
print, description
| Name | Type | Description |
|---|---|---|
locator |
CONST_OBJECT Profile.Matching.PatternMatcher |
Input pattern matcher. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
String description of the pattern matcher. |
print(Profile.Matching.PatternMatcher.toString(patternMatcher))
Script
Provides general functions to communicate with the system and other Apps. E.g. functions to register script functions/-events to the system, in order to call them from other CROWNS. These functions are only available from scripting!
Overview
Functions
callFunction()
Call a CROWN function generically by name from a script context. This is useful if the function name is set dynamically and not known. This call blocks until the function has run and returns its return-values.
| Name | Type | Description |
|---|---|---|
funcName |
STRING |
The function name of the function to call |
param1 |
AUTO |
First parameter for the function call (optional) |
param2 |
AUTO |
second parameter for the function call (optional) |
param3 |
AUTO |
third parameter for the function call (optional) |
param4 |
AUTO |
fourth parameter for the function call (optional) |
param5 |
AUTO |
fifth parameter for the function call (optional) |
param6 |
AUTO |
sixth parameter for the function call (optional) |
param7 |
AUTO |
seventh parameter for the function call (optional) |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if the function has been called successfully, false if function name was not a valid served function or wrong parameters passed to call the function. |
result1 |
AUTO |
First result of the function call (optional) |
result2 |
AUTO |
second result of the function call (optional) |
result3 |
AUTO |
third result of the function call (optional) |
result4 |
AUTO |
fourth result of the function call (optional) |
result5 |
AUTO |
fifth result of the function call (optional) |
result6 |
AUTO |
sixth result of the function call (optional) |
result7 |
AUTO |
seventh result of the function call (optional) |
success, ret1, ret2 = Script.callFunction("theFuncName", param1, param2)
callFunctionAsync()
Call a CROWN function generically by name from a script context without waiting for the return value. This is useful if the function name is set dynamically and not known. This call does not block if the function is implemented in another thread/script and return-values are discarded. The call isn’t guaranteed to be run async: It depends on the implementation of the calling function.
| Name | Type | Description |
|---|---|---|
funcName |
STRING |
The function name of the function to call |
param1 |
AUTO |
First parameter for the function call (optional) |
param2 |
AUTO |
second parameter for the function call (optional) |
param3 |
AUTO |
third parameter for the function call (optional) |
param4 |
AUTO |
fourth parameter for the function call (optional) |
param5 |
AUTO |
fifth parameter for the function call (optional) |
param6 |
AUTO |
sixth parameter for the function call (optional) |
param7 |
AUTO |
seventh parameter for the function call (optional) |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if the function has been called successfully, false if function name was not a valid served function |
success = Script.callFunctionAsync("theFuncName", param1, param2)
deregister()
Deregisters a function from an event, which was registered at the event before. Deregistration are automatically done on script destruction.
| Name | Type | Description |
|---|---|---|
eventName |
STRING |
The event name to deregister from. |
consumer |
STRING |
The function name which was used for registering. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successfully deregistered. |
Script.deregister("Crown.Event","MyFunction")
disableGarbageCollectionByEngine()
Disables the automatic collectgarbage() calls by the engine for the current Lua script interpreter which are done after each script callback. Per default there is a full garbage collector run done on leaving the interpreter, to avoid non-deterministic behaviour due to no released CROWN objects from the interpreter. This disableGarbageCollectionByEngine()-function can be called at the beginning of a script in global scope to disable the automatic collectgarbage()-calls. If this function is used, the user has to know how lua garbage collection works and needs to take care by himself of the garbage collector settings of the Lua interpreter. The user also can manually release objects and handles using the function "Script.releaseObject". For easier usage of disabled engine garbage collection, this function also changes the garbagecollector settings to the following more aggressive settings: - collectgarbage("setpause", 100) — means "no pause". Lua default is 200 which is that the collection cycle starts only when the used memory is doubled. - collectgarbage("setstepmul", 400) — increases the work which each incremental step does. Lua default is 200. To tune the settings even more for your application, please read more about garbage collector in lua documentation. Basic suggestion: If the memory increases in your application and memory isn’t collected fast enough, increase the "setstepmul" to larger values than 400.
Script.disableGarbageCollectionByEngine()
isEventRegistered()
Returns true if a served event has minimum one registration active. Only works with events which were served by this script using the Script.serveEvent-function.
| Name | Type | Description |
|---|---|---|
localEventName |
STRING |
Name of the event which is to be notified. The event needs to match the localEventName used in ServeEvent-function. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if there is minimum one registration active. |
registrationCount |
INT |
If there is a registration, this value contains the number of registrations, otherwise nil. |
Script.isEventRegistered("MyEvent")
isServedAsEvent()
Returns true if the specified event name is served anywhere in the CROWN framework. This is especially useful when registering to dynamic events and checking before if the event is still served and available.
| Name | Type | Description |
|---|---|---|
eventName |
STRING |
The event name which should be checked |
| Name | Type | Description |
|---|---|---|
isServed |
BOOL |
True if the specified event name is currently served as CROWN event in the framework |
isServedAsFunction()
Returns true if the specified function name is served anywhere in the CROWN framework. This is especially useful when calling dynamic functions and checking before if the function is still served and available.
| Name | Type | Description |
|---|---|---|
funcName |
STRING |
The function name which should be checked |
| Name | Type | Description |
|---|---|---|
isServed |
BOOL |
True if the specified function name is currently served as CROWN function in the framework |
notifyEvent()
Use to notify an event which was served by the Script.serveEvent function by this app. Add any parameter to notify along with this event to the argument list.
| Name | Type | Description |
|---|---|---|
localEventName |
STRING |
Name of the event which is to be notified. The event needs to match the localEventName used in ServeEvent-function. |
parameters |
AUTO |
Parameters to notify. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully notified, false otherwise |
Script.notifyEvent("MyEvent", value1, value2)
register()
Registers a function to an event. Registrations are possible only once per function and event. Further register calls for same combination return false. Registrations are always successfully done although the event might not be served already. In future the event still could get served and fired. If successfully registered there is a second return value added which indicates if the registered event is currently served by someone. This is useful to verify the wiring of an application. All calls to the registered function are executed sequentially in the context of the registering application. Execution of the event notifier is not blocked and event callback calls are queued up at the registered application. If there is a function pointer used for registering, the execution of the function always happens in the current script context (pay attention if registering another apps functions to use register function by name).
| Name | Type | Description |
|---|---|---|
eventName |
STRING |
The event name to register to. |
consumer |
STRING |
Name of the function to be called if the event occurs. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if successfully registered. False if the function is already registered on that event. |
eventServed |
BOOL |
If registration was successful, this second parameter is added. True if the registered event is really served by someone. |
Script.register("Crown.Event","MyFunction")
releaseObject()
Explicitly releases an object or handle from the script. If there is no one other holding a reference to the object, it is freed. This is useful if the user does not want to wait until the garbage collector releases it but does it at an explicit location.
| Name | Type | Description |
|---|---|---|
objectToRelease |
AUTO |
The object(s) or handle(s) to release |
Script.releaseObject(obj)
serveEvent()
Call to publish an event, so other apps can register on. The event must be specified in the app manifest over the AppStudio AppProperties Serves-tab.
| Name | Type | Description |
|---|---|---|
crownEventName |
STRING |
The name used in the CROWN system. The app name must be prefixed to have a full qualified CROWN name (e.g. 'MyApp.MyEvent') |
localEventName |
STRING |
Name of the event inside the lua script. Use this name for the Script.notifyEvent() function. |
parameterListType |
STRING |
DEPRECATED! Not needed to be specified if the event is declared in the manifest over AppStudio AppProperties Serves-tab! Comma separated parameter definition list, e.g.: 'bool,string,int,object'. Types match the crown types. Syntax for one type: 'qualifier typename:multiplicity:alias' |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully served, false otherwise |
Script.serveEvent("MyApp.MyEvent", "MyEvent")
serveFunction()
Use to publish a lua function, so it can be called from other Apps. The function must be specified in the app manifest over the AppStudio AppProperties Serves-tab. All calls of the served function are executed sequentially in the context of the serving application. Execution of the caller is deferred until the function returns. There is no need for additional synchronization.
| Name | Type | Description |
|---|---|---|
crownFunctionName |
STRING |
The name used in the CROWN system. The app name must be prefixed to have a full qualified CROWN name (e.g. 'MyApp.MyFunc') |
localFunctionName |
STRING |
Name of the function inside the lua script, e.g. 'MyFunc' |
parameterTypeList |
STRING |
DEPRECATED! Not needed to be specified if the function is declared in the manifest over AppStudio AppProperties Serves-tab! Comma separated parameter definition list, e.g.: 'bool,string,int,object'. Types match the crown types. Syntax for one type: 'qualifier typename:multiplicity:alias' |
returnTypeList |
STRING |
DEPRECATED! Not needed to be specified if the function is declared in the manifest over AppStudio AppProperties Serves-tab! Comma separated return value definition list, e.g.: 'bool,string,int,object'. Types match the crown types. Syntax for one type: 'qualifier typename:multiplicity:alias' |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully served, false otherwise |
Script.serveFunction("MyApp.MyFunction", "MyFunction")
sleep()
Stops the execution of the interpreter at the given position and releases the processor. This can be used to delay the script at a given position. The usage of this function should be avoided for released applications but can be useful for testing. The script can be stopped also if it is sleeping at this position. During sleeping the lua script cannot handle events or other function calls. They are queued up and will be handled if the caller of this sleep returns from the script.
| Name | Type | Description |
|---|---|---|
sleepTimeMs |
INT |
The time in milliseconds to sleep. The effective sleept time could be higher. |
Script.sleep(50)
startScript()
Starts a new script with specified filename in a new interpreter, running in a new task context. This function is used to run several script tasks and interpreters inside a single app. One example where this is useful is if there are long-running blocking function calls, but the app should still stay responsive to events while these calls are executed. One way to realize this is is to use multiple apps, but using multiple scripts within one app has advantages: There is only one app that needs to be deployed, and the scripts within one app can share common lua code via require. The started scripts can use the CROWN framework to communicate with each other, the same way that communication between separate apps works: Via serving and using of functions and events. The script is started synchronous, so this function blocks until the main script scope of the newly started script has ran. After the main script scope has ran, the started script keeps active in the background and can react to events and functions calls to served functions. The lifetime of the script is bound to the app within it was started. Limitations: - The script file to be started must be located directly in the scripts/ directory of the app, it is not possible to start scripts which are located in a subdirectory. - It is not possible to debug a script that is started with this function in AppStudio directly. A possible workaround is to manually change the startScript() call for the specific script to be debugged to a require() to make it execute directly in the context of the main script of the app.
| Name | Type | Description |
|---|---|---|
fileName |
STRING |
The file name of the Lua file which is to be started in a new interpreter. The file extension '.lua' can be omitted. The script file to be started must be located directly in the scripts/ directory of the app, it is not possible to start scripts which are located in a subdirectory. |
priority |
ENUM Priority |
Priority of the task running the new interpreter. The available priority levels are the same as the levels that can be selected for an app in the app properties in AppStudio. The parameter is optional. By default, the priority of the script that calls the function is used. In case of the app main script, this is the app priority. |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if the script file could be successfully loaded and started. |
local success = Script.startScript("somescript.lua")
Script.Queue
Provides functionality to create new call queue. Per default each script has a one single default call queue to which all incoming calls are enqueued as they come in. Separate queues are useful to e.g. increase or decrease the queue priority or limit certain incoming events. The default queue of the script has priority 'MID'. All queues on the same priority are scheduled fair, which means each queue can process one queued call in each cycle. The handle to the queue needs to be held so that the queue stays active. If the handle is lost, the events are enqueued again in the default queue and currently queued events are lost. The limitation of queue sizes and discarding if full with the setMaxQueueSize and setDiscardIfFull functions is only possible, if the call is an event callback. For served function executions the limitation is not possible, because the functions always need to be executable and need a return value.
Overview
Functions
clear()
Clears all currently queued calls. This only works for event callbacks and not for function callbacks, because function calls always need a return value. Pay attention that directly during returning from this function there might be events already added again.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
Script.Queue.clear(handle)
create()
Creates a new instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the new instance |
-- Creates a new queue for the current running script with higher priority:
function myCallback()
end
queueHandle = Script.Queue.create()
queueHandle:setPriority("HIGH")
queueHandle:setFunction(myCallback)
-- Now register the callback at an event:
SomeProvider.register(provHandle, "OnSomeEvent", myCallback)
getSize()
Returns the current number of queue calls. Pay attention that directly during returning from this function there might be events already added again.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
| Name | Type | Description |
|---|---|---|
size |
INT |
The current queue size |
size = Script.Queue.getSize(handle)
setDiscardIfFull()
Sets the behaviour for adding events to the queue if the queue is full. Per default the oldest element is discarded. To discard the newest to be added element, call this function with parameter true.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
bDiscardIfFull |
BOOL |
Set to true to discard the newest item which is currently added instead of discarding the oldest element |
Script.Queue.setDiscardIfFull(handle, true)
setFunction()
Sets the function(s) which are handled by this queue. After this call, the specified functions are removed from the default script queue and added to this queue. So this call should be done as last call. This can be a lua function reference or local function name, and also be a served function name. To prioritize calls to a function served over Script.serveFunction, the served function name has to be used, and the function needs to be served before this call.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
function |
STRING |
The function or array of functions which should be handled by this queue. |
Script.Queue.setFunction(handle, callbackFunc)
setMaxQueueSize()
Sets the maximum queue size of the call queue. This only works for event callbacks and not for function callbacks, because function calls always need a return value. Per default the queue is set to infinite size (=0). If the max queue size is reached, the oldest element is discarded per default. To change that behaviour use the setDiscardIfFull-Function.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
maxQueueSize |
INT |
The max number of events to queue. Per default 0 (=infinite) |
Script.Queue.setMaxQueueSize(handle, 10)
setPriority()
Sets the relative priority of the queue compared to other queues of the script. Per default the priority MID is set, if this function is not called
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
prio |
ENUM Priority |
The new priority to set |
Script.Queue.setPriority(handle, "LOW")
SensorData
Provides access to additional sensor data information like origin and time stamp that is sent along with the actual measurement data.
Overview
Functions
getFrameNumber()
Returns the frame number (incremented by one for each measurement).
| Name | Type | Description |
|---|---|---|
sensordata |
CONST_OBJECT SensorData |
Handle to the instance. |
| Name | Type | Description |
|---|---|---|
frameno |
INT |
The frame number. |
local frameNumber = SensorData.getFrameNumber(theSensorData)
getID()
Returns an application specific ID (e.g. object ID).
| Name | Type | Description |
|---|---|---|
sensordata |
CONST_OBJECT SensorData |
Handle to the instance. |
| Name | Type | Description |
|---|---|---|
id |
INT |
Returns the ID. |
local id = SensorData.getID(theSensorData)
getMetaData()
Get the MetaData which is associated with the SensorData object. The MetaData object is optional and can contain dynamically configurable additional SensorData. The 'getMetaData' function returns an object of the type Container. The content can be accessed via the Container API.
| Name | Type | Description |
|---|---|---|
sensordata |
CONST_OBJECT SensorData |
Input data to get the MetaData from. |
| Name | Type | Description |
|---|---|---|
metadata |
OBJECT Container |
Optional MetaData object. |
local metaData = SensorData.getMetaData(theSensorData)
getName()
Returns the component name of the corresponding data object (e.g. DepthImage or GreyImage).
| Name | Type | Description |
|---|---|---|
sensordata |
CONST_OBJECT SensorData |
Handle to the instance. |
| Name | Type | Description |
|---|---|---|
name |
STRING |
The component name of the corresponding data object. |
local name = SensorData.getName(theSensorData)
getOrigin()
Returns the origin (e.g. device name).
| Name | Type | Description |
|---|---|---|
sensordata |
CONST_OBJECT SensorData |
Handle to the instance. |
| Name | Type | Description |
|---|---|---|
origin |
STRING |
Returns the data origin. |
local origin = SensorData.getOrigin(theSensorData)
getTimestamp()
Returns the time stamp (in microseconds).
| Name | Type | Description |
|---|---|---|
sensordata |
CONST_OBJECT SensorData |
Handle to the instance. |
| Name | Type | Description |
|---|---|---|
timestamp |
INT |
The time stamp value (in microseconds). |
local timeStamp = SensorData.getTimestamp(theSensorData)
toString()
Get a string representation of the SensorData.
| Name | Type | Description |
|---|---|---|
sensordata |
CONST_OBJECT SensorData |
Input data to get the string representation. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
String representation of the SensorData |
print("SensorData: " .. SensorData.toString(theSensorData))
SerialCom
Provides raw serial communication access. First a new SerialCom client needs to be created using the create function. Afterwards the baudrate and the other settings need to be done. Then a call to the open-function opens the serial port and transmit calls and OnReceive events are possible. Data could be transmitted to the server using the "transmit" function. Data could be received by a register to the "OnReceive" event or by calling the blocking receive()-function. The transmitted and received data is raw data. It could get automatically framed for transmitting and receiving can be automatically parsed if setting a framing with the "setFraming" function. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.
Overview
Functions
close()
Closes the serial handle.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
SerialCom.close(handle)
create()
Creates a serial communication interface instance if port exists and not already in use.
| Name | Type | Description |
|---|---|---|
portName |
ENUM SerialPorts |
The (device dependent) name of the serial port which should be opened. |
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). Nil if not available or already in use. |
handle = SerialCom.create("SER1")
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
isOpened()
Determine whether the serial port is open or not.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
| Name | Type | Description |
|---|---|---|
isOpen |
BOOL |
true if the COM port is open, false if not |
isOpen = SerialCom.isOpened(handle)
open()
Opens the serial connection that has been configured with the set* functions.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
| Name | Type | Description |
|---|---|---|
isOpen |
BOOL |
Returns true if interface could be opened. If false, the port might be in use already. |
success = SerialCom.open(handle)
receive()
Receives data from the client with a specified timeout. If timeout is zero then it directly returns. The data could be framed if the "setFraming" function was called before. Incoming data between multiple receive calls is queued per message. There is a fix receive queue size of 10 packets per default and can be changed using the setReceiveQueueSize()-function. More data is discarded.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
timeout |
INT |
Timeout in ms to wait for received data. 0 is default and means directly return. |
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The data which was received |
data = SerialCom.receive(handle, 5000)
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
setBaudRate()
Sets the baudrate. Default is '57600'.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
baudRate |
INT |
One of 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200 |
SerialCom.setBaudRate(handle, 9600)
setDataBits()
Sets the number of data bits. Default is '8'.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
dataBits |
INT |
8 or 7 |
SerialCom.setDataBits(handle, 8)
setFlowControl()
Enables or disables hardware flow control. Default is 'false'.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
enabled |
BOOL |
true to enable flow control, false to disable |
SerialCom.setFlowControl(handle, false)
setFraming()
Sets the framing which is to be used. If not set the default framing is no framing (raw byte/packet-wise connection). Framing could be also explicitly disabled by calling this function with 2 empty binary data for rx and tx. One framing part could be maximum size of 9 bytes. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded. The close and open functions has to be called afterwards so that the setting gets active.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
rxStart |
BINARY |
Start framing for receiving, could be empty string. Maximum size of 9. |
rxStop |
BINARY |
Stop framing for receiving. If empty then all raw data is received. Maximum size of 9. |
txStart |
BINARY |
Start framing for sending, could be empty string. Maximum size of 9. |
txStop |
BINARY |
Stop framing for sending, could be empty string. Maximum size of 9. |
SerialCom.setFraming(handle, "", "", "", "")
setFramingBufferSize()
Sets the size of the internal framing parser buffer which is used if there is a rx or tx framing set using the setFraming function. If the rx or tx framing isn’t set, its buffer size has no effect. This size is the maximum size of a packet which can be parsed by the framing. The size is used for start and stop framing. Default is 10240 bytes. The close and open functions have to be called afterwards for activating the setting.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
rxBufSize |
INT |
The new framing buffer size for framed receiving. |
txBufSize |
INT |
The new framing buffer size for framed transmitting. |
SerialCom.setFramingBufferSize(handle, 21000, 21000)
setHandshake()
Enables or disables handshake. Default is 'false'.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
enabled |
BOOL |
true to enable Xon/Xoff handshake, false to disable |
SerialCom.setHandshake(handle, true)
setParity()
Sets the parity. Default is 'N'.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
parity |
CHAR |
One of "N", "O", "E", "M", "S" (None, Odd, Even, Mark, Space) |
SerialCom.setParity(handle, "N")
setReceiveQueueSize()
Sets the internal queue size for the receive()-function. Default is 10 packets and discarding the oldest item and warn if overrun occurs. Set to 0 to disable the queue and receiving from the receive()-function, which also increases performance if only receiving over OnReceive-event.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the UDP socket |
queueSize |
INT |
The new receive queue size. |
bDiscardIfFull |
BOOL |
Set to true to discard the newest item which is currently added instead of discarding the oldest element. Default is false. |
warnOverruns |
BOOL |
Set to false to disable warning on overruns when using the receive()-function. Default is true. |
SerialCom.setReceiveQueueSize(handle, 50)
setStopBits()
Sets the number of stop bits. Default is '1'.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
stopBits |
INT |
1 or 2 |
SerialCom.setStopBits(handle, 1)
setTermination()
Enables the internal termination of the serial interface. Default is 'false'.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
terminated |
BOOL |
true to enable internal termination, false to disable |
SerialCom.setTermination(handle, true)
setType()
Selects the type of the serial interface. Default is 'RS232'.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
type |
ENUM SerialComTypes |
Interface type which is available on the device. E.g. 'RS232', 'RS422', 'RS485' |
SerialCom.setType(handle, "RS232")
transmit()
Transmits the data on the serial handle. If framing is set using the "setFraming" function, then the framing characters are automatically prefixed and suffixed to the transmitted data. Blocks until data has been transmitted.
| Name | Type | Description |
|---|---|---|
ifHandle |
HANDLE |
Handle to the Serial Communication Interface that has been returned by SerialCom.create(). |
data |
BINARY |
The data which should be sent |
| Name | Type | Description |
|---|---|---|
numberOfBytesTransmitted |
INT |
Number of bytes transmitted; 0 if transmit failed |
SerialCom.transmit(handle, "data to transmit")
Events
OnReceive
The on receive event which is thrown for every new received data.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
This is a handle event and must be registered on the handle |
data |
BINARY |
The received data |
Shape
A 2D geometric primitive. A Shape can be one of the geometric types Line, LineSegment, Polyline, Rectangle, Circle, Ellipse, Arc or Sector. The Shape object is represented in mathematical analytical form. Operations such as finding intersection points, distances and transforming the Shape are for this reason efficiently computed. Note when used in context of images: The Shapes are defined in the image world coordinate system, i.e., in world scale (typically millimeters) and not in pixel coordinates. The image world coordinate system is left handed, with the x-axis pointing rightwards and the y-axis pointing downwards, and the origin centered at the upper left pixel. In this coordinate system, positive translations along the y-axis will shift the shape downwards, and positive rotations are clockwise. Thus, this is different compared to usage in a right-handed coordinate system context.
Overview
appendPoint(), clone(), contains(), createArc(), createCircle(), createEllipse(), createLine(), createLineSegment(), createPolyline(), createRectangle(), createSector(), cropLine(), getArcParameters(), getArea(), getBoundingBox(), getBoundingBoxOriented(), getBounds(), getCenterOfGravity(), getCircleParameters(), getClosestContourPoint(), getCompactness(), getContourPoints(), getConvexHull(), getConvexity(), getEllipseParameters(), getElongation(), getIntersectionAngle(), getIntersectionPoints(), getLineDistance(), getLineParameters(), getPerimeterLength(), getPolylineParameters(), getRadius(), getRectangleParameters(), getSectorParameters(), getType(), isClosed(), rotate(), toImage(), toLine(), toPixelRegion(), toPolyline(), toShape3D(), toString(), transform(), translate()
Functions
appendPoint()
Append a point to a polyline shape.
| Name | Type | Description |
|---|---|---|
shape |
OBJECT Shape |
The shape to modify. Must be a polyline shape. |
point |
CONST_OBJECT Point |
2D point to add. |
Shape.appendPoint(polyline, Point.create(x, y))
clone()
Create an independent copy of this shape. If the input is a vector of shapes, the output is a vector of shapes.
| Name | Type | Description |
|---|---|---|
inputShape |
CONST_OBJECT Shape |
The shape to clone. |
| Name | Type | Description |
|---|---|---|
outputShape |
OBJECT Shape |
The new copy. |
outputShape = Shape.clone(inputShape)
contains()
Check if the input point is contained within the enclosed area of the given shape. Always returns false if the shape is not closed. If more than one shape is provided true is returned if the point is inside any of the shapes. If more than one point is provided a vector is returned with one value for each input point.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Closed shape enclosing an area |
point |
CONST_OBJECT Point |
Point (2D) to check if contained within the area |
| Name | Type | Description |
|---|---|---|
isInside |
BOOL |
True if the point is contained within the enclosed area, false if not |
isInside = Shape.contains(shape, point)
createArc()
Create an arc shape (part of a circle). Radius and deltaAngle must be non-negative. By providing vectors of centers, radii, angles and delta angle several arcs can be created. All vectors must be of equal length.
| Name | Type | Description |
|---|---|---|
center |
CONST_OBJECT Point |
Center point (2D) of the arc. Can also be a vector of center points to create several arcs. |
radius |
FLOAT |
Arc radius. Can also be a vector of radii to create several arcs. |
angle |
FLOAT |
Angle where the arc starts, in radians. Can also be a vector of angles to create several arcs. |
deltaAngle |
FLOAT |
The angular length of the arc, in radians. Can also be a vector of delta angles to create several sectarcsors. |
| Name | Type | Description |
|---|---|---|
arc |
OBJECT Shape |
The created arc, or vector of arcs for for vector input. |
arc = Shape.createArc(centerPoint, radius, angle, deltaAngle)
createCircle()
Create circle shape(s). By providing vectors of centers and radii, several circles can be created. All vectors must be of equal length.
| Name | Type | Description |
|---|---|---|
center |
CONST_OBJECT Point |
A single 2D Point or a vector of points. If the input is a vector, a vector of circles is created. |
radius |
FLOAT |
Circle radius. Must be non-negative. Can also be a vector to create several circles. |
| Name | Type | Description |
|---|---|---|
circle |
OBJECT Shape |
The created circle or vector of circles. |
circle = Shape.createCircle(centerPoint, radius)
createEllipse()
Create an ellipse shape. Radii must be non-negative. By providing vectors of centers, radiusX, radiusY and rotation, several ellipses can be created. All vectors must be of equal length.
| Name | Type | Description |
|---|---|---|
center |
CONST_OBJECT Point |
Center point (2D). Can also be a vector of centre points to create several ellipses. |
radiusX |
FLOAT |
Radius along the x axis (before rotation). Can also be a vector of radii to create several ellipses. |
radiusY |
FLOAT |
Radius along the y axis (before rotation). Can also be a vector of radii to create several ellipses. |
rotation |
FLOAT |
Ellipse rotation in radians. Can also be a vector of rotations to create several ellipses. A positive rotation rotates the x-axis towards the y-axis. Note that when used as region for an image, the image has a left-hand system with the y-axis pointing downwards, in which a positive rotation means a clockwise direction. |
| Name | Type | Description |
|---|---|---|
ellipse |
OBJECT Shape |
The created ellipse, or vector of ellipses for for vector input. |
ellipse = Shape.createEllipse(centerPoint, radiusX, radiusY, rotation)
createLine()
Create an infinite line shape that connects (and extends beyond) two given points. The points must not be the same. By providing vectors of end-points, several infinite lines can be created. The vectors must be of equal length.
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
A point (2D) on the line. Can also be a vector of points to create several lines. |
point2 |
CONST_OBJECT Point |
Another point (2D) on the line. Can also be a vector of points to create several lines. |
| Name | Type | Description |
|---|---|---|
line |
OBJECT Shape |
The created line, or vector of lines for for vector input. |
line = Shape.createLine(point1, point2)
createLineSegment()
Create a finite length line segment between two given endpoints. By providing vectors of end-points, several line segments can be created.
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
First endpoint (2D) of the line segment. Can also be a vector of points to create several line segments. |
point2 |
CONST_OBJECT Point |
Second endpoint (2D) of the line segment. For vector input the length of the vector must match the vector containing the first endpoints |
| Name | Type | Description |
|---|---|---|
lineSegment |
OBJECT Shape |
The created line segment, or vector of line segments for for vector input. |
lineSegment = Shape.createLineSegment(point1, point2)
createPolyline()
Create a polyline shape (sequence of line segments connected to an open contour or closed polygon).
| Name | Type | Description |
|---|---|---|
points |
CONST_OBJECT Point |
List of points (2D) to connect to a polyline |
closed |
BOOL |
If true, the first and last points are connected to form a closed polygon. Otherwise it becomes an open contour. |
| Name | Type | Description |
|---|---|---|
polyline |
OBJECT Shape |
The created polyline or polygon shape |
polyline = Shape.createPolyline(points, true)
createRectangle()
Create a rectangle shape. Width and height must be non-negative. By providing vectors of centers, width, height and rotation, several rectangles can be created. All vectors must be of equal length.
| Name | Type | Description |
|---|---|---|
center |
CONST_OBJECT Point |
Center point (2D) of the rectangle. Can also be a vector of center points to create several rectangles. |
width |
FLOAT |
Rectangle width (size along the x axis before rotation). Can also be a vector of center points to create several rectangles. |
height |
FLOAT |
Rectangle height (size along the y axis before rotation). Can also be a vector of heights to create several rectangles. |
rotation |
FLOAT |
Optional rectangle rotation in radians, default is zero. A positive rotation rotates the x-axis towards the y-axis. Note that when used as region for an image, the image has a left-hand system with the y-axis pointing downwards, in which a positive rotation means a clockwise direction. Can also be a vector of rotations to create several rectangles. |
| Name | Type | Description |
|---|---|---|
rectangle |
OBJECT Shape |
The created rectangle shape, or vector of rectangles for for vector input. |
rectangle = Shape.createRectangle(center, width, height, rotation)
createSector()
Create a circular sector defining a region contained within two angles, an inner and an outer radius. Radii and deltaAngle must be non-negative, outerRadius must be larger than innerRadius. By providing vectors of centers, innerRadius, outerRadius, angle and deltaAngle several sectors can be created. All vectors must be of equal length.
| Name | Type | Description |
|---|---|---|
center |
CONST_OBJECT Point |
Center point of the circle from which the sector is defined. Can also be a vector of center points to create several sectors. |
innerRadius |
FLOAT |
Inner radius of the sector. Can also be a vector of inner radii to create several sectors. |
outerRadius |
FLOAT |
Outer radius of the sector. Can also be a vector of outer radii to create several sectors. |
angle |
FLOAT |
Angle where the sector starts, in radians. Can also be a vector of angles to create several sectors. |
deltaAngle |
FLOAT |
The angular length of the sector, in radians. Can also be a vector of delta angles to create several sectors. |
| Name | Type | Description |
|---|---|---|
sector |
OBJECT Shape |
The created sector, or vector of sectors for for vector input. |
sector = Shape.createSector(center, innerRadius, outerRadius, angle, deltaAngle)
cropLine()
Returns the part of a line within a rectangle as a new line segment. If the line does not intersect the rectangle, nil is returned. Several lines in a vector can be cropped at once, in which case all lines must be within the box for the call to succeed.
| Name | Type | Description |
|---|---|---|
line |
CONST_OBJECT Shape |
The line shape to be cropped, or a vector of lines to be cropped. |
rectangle |
CONST_OBJECT Shape |
The rectangle to keep the line within. |
| Name | Type | Description |
|---|---|---|
line |
OBJECT Shape |
The part of the line within the rectangle as a line segment, or a vector of line segments. Nil is returned if any line is outside the box. |
lineSegment = Shape.cropLine(line, rectangle)
getArcParameters()
Get the parameters defining the arc. Can only be called for arc shapes (returns nil otherwise). A vector of arc shapes can be provided, in which case vectors of parameters are returned.
| Name | Type | Description |
|---|---|---|
arc |
CONST_OBJECT Shape |
Input arc shape or vector of arc shapes. |
| Name | Type | Description |
|---|---|---|
center |
OBJECT Point |
Center point of the circle from which the arc is defined, or vector of center points for vector input. |
radius |
FLOAT |
Radius of the arc, or vector of radii for vector input. |
angleRad |
FLOAT |
Angle where the arc starts, in radians, or vector of angles for vector input. |
deltaAngleRad |
FLOAT |
The angular length of the arc, in radians, or vector of angular lengths for vector input. |
center, radius, angleRad, deltaAngleRad = Shape.getArcParameters(arc)
getArea()
Get the area of the region enclosed by a 2D Shape. A vector of shapes can be provided, in which case a vector of areas is returned.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or vector of shapes. |
| Name | Type | Description |
|---|---|---|
area |
FLOAT |
Area of shape, or vector of areas for vector input. |
area = Shape.getArea(shape)
getBoundingBox()
Get a rectangular axis-aligned bounding box of the shape (minimum box that contains the shape). The returned box is another Shape object. To get the actual bounds as float values, call getBounds.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or shapes |
| Name | Type | Description |
|---|---|---|
boundingBox |
OBJECT Shape |
Axis-aligned bounding box as a rectangle shape, or vector for vector input. |
boundingBox = Shape.getBoundingBox(shape)
getBoundingBoxOriented()
Gets a rectangular rotated bounding box of the given shape. This is the minimum area rectangle that still contains the shape. The return box is another Shape object.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or shapes. |
| Name | Type | Description |
|---|---|---|
minimumAreaRectangle |
OBJECT Shape |
The oriented minimum area bounding box, or vector for vector input. |
minimumAreaRectangle = Shape.getBoundingBoxOriented(shape)
getBounds()
Get the bounds of the shape as float values. Fails for invalid and unbounded shapes.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape |
| Name | Type | Description |
|---|---|---|
xMin |
FLOAT |
Minimum x coordinate |
yMin |
FLOAT |
Minimum y coordinate |
xMax |
FLOAT |
Maximum x coordinate |
yMax |
FLOAT |
Maximum y coordinate |
xMin, yMin, xMax, yMax = Shape.getBounds(shape)
getCenterOfGravity()
Get the center of gravity of the region enclosed within the shape for closed shapes. For open shapes, the center of gravity of the contour is returned. Returns nil for infinite or invalid shapes.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or vector of shapes. |
| Name | Type | Description |
|---|---|---|
centerOfGravity |
OBJECT Point |
Center of gravity as a 2D Point, or vector of points for vector input. |
point = Shape.getCenterOfGravity(shape)
getCircleParameters()
Get the parameters defining the circle. Can only be called for circle shapes (returns nil otherwise). A vector of circle shapes can be provided, in which case vectors of parameters are returned.
| Name | Type | Description |
|---|---|---|
circle |
CONST_OBJECT Shape |
Input circle shape or vector of circle shapes. |
| Name | Type | Description |
|---|---|---|
center |
OBJECT Point |
Center point of the circle, or vector of center points for vector input. |
radius |
FLOAT |
Radius of the circle, or vector of radii for vector input. |
center, radius = Shape.getCircleParameters(circle)
getClosestContourPoint()
Get the closest point on a shape contour to a given external point. Fails if the point is not a 2D point. If there are more than one shape provided the closest point on any shape countour is returned. If there are more than one point provided one point is returned for each input point.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Shape to process. |
point |
CONST_OBJECT Point |
Point to process. |
| Name | Type | Description |
|---|---|---|
closestPoint |
OBJECT Point |
Closest point on any of the shapes. |
distance |
FLOAT |
The distance to the closest point. |
closestPoint = Shape.getClosestContourPoint(shape, point)
getCompactness()
Gets a measure of how compact a shape is, as a number between 0.0 and 1.0. A circle has compactness 1.0. The measure is calculated as (4*pi*Area)/perimeter^2. Degenerate shapes has compactness zero.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or vector of shapes. |
| Name | Type | Description |
|---|---|---|
compactness |
FLOAT |
Compactness of a shape, or vector for vector input. |
compactness = Shape.getCompactness(shape)
getContourPoints()
Get the points defining the shape contour. Only supported for shapes consisting of a finite number of points (line segments, rectangles and polylines). To get a polygon approximation of a circle or ellipse, use toPolyline.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Shape to process |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
List of points (2D) that approximates or represents the input shape. |
points = Shape.getContourPoints(shape)
getConvexHull()
Gets the convex hull of a given shape. Currently fails if the shape is something other than a polyline. Convert general shapes to polylines using Shape.toPolyline.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Shape or shapes to process. |
| Name | Type | Description |
|---|---|---|
hull |
OBJECT Shape |
Resulting convex hull as a polyline, or vector for vector input. |
hull = Shape.getConvexHull(shape)
getConvexity()
Returns a measure of how convex a given shape is, as a number between 0.0 and 1.0. It is given as a quotient between the area of the shape and its convex hull. A convex object has convexity 1.0. All open shapes such as lines, arcs and open polylines return 0.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or vector of shapes. |
| Name | Type | Description |
|---|---|---|
convexity |
FLOAT |
A measure of how convex the shape is, or vector of measurements for vector input. |
convexity = Shape.getConvexity(shape)
getEllipseParameters()
Get the parameters defining the ellipse. Can only be called for ellipse shapes (returns nil otherwise). A vector of ellipse shapes can be provided, in which case vectors of parameters are returned.
| Name | Type | Description |
|---|---|---|
ellipse |
CONST_OBJECT Shape |
Input ellipse shape or vector of ellipse shapes. |
| Name | Type | Description |
|---|---|---|
center |
OBJECT Point |
Center point (2D), or vector of center points for vector input. |
radiusX |
FLOAT |
Radius along the x axis (before rotation), or vector of radii for vector input. |
radiusY |
FLOAT |
Radius along the y axis (before rotation), or vector of radii for vector input. |
rotationRad |
FLOAT |
Ellipse rotation, in radians. Vector of rotations for vector input. |
center, radiusX, radiusY, rotationRad = Shape.getEllipseParameters(ellipse)
getElongation()
Get the a measure of elongation of a shape. It is calculated as lengthAlongMajorAxis/lengthAlongMinorAxis and is therefore a number between 1.0 (e.g., a circle) and infinity (e.g., a line). For some shapes, i.e, Polyline, Arc and Sector, the elongation of the shape bounding box is returned.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or vector of shapes. |
| Name | Type | Description |
|---|---|---|
elongation |
FLOAT |
Elongation, or vector of elongations for vector input. |
elongation = Shape.getElongation(shape)
getIntersectionAngle()
Get angle of the intersection between two lines or line segments. If the line segments do not intersect the lines are extrapolated to calculate the intersection angle.
| Name | Type | Description |
|---|---|---|
line1 |
CONST_OBJECT Shape |
First shape. Must be a line or line segment. |
line2 |
CONST_OBJECT Shape |
Second shape. Must be a line or line segment. |
| Name | Type | Description |
|---|---|---|
angle |
FLOAT |
Intersection angle, in radians. |
angle = Shape.getIntersectionAngle(line1, line2)
getIntersectionPoints()
Get points on the intersection between two shape contours.
| Name | Type | Description |
|---|---|---|
shape1 |
CONST_OBJECT Shape |
First shape to intersect. |
shape2 |
CONST_OBJECT Shape |
Second shape to intersect. |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
List of intersection points. |
points = Shape.getIntersectionPoints(shape1, shape2)
getLineDistance()
Returns the minimum and maximum distance from all points on the shape to the reference line. Distances are measured orthogonal to the reference line. The query shape should have finite size.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
The shape or shapes to check distance to. |
referenceLine |
CONST_OBJECT Shape |
The reference line. |
| Name | Type | Description |
|---|---|---|
minDist |
FLOAT |
The orthogonal distance from the line to the closest point on the shape, or nil if projection failed. Vector with distances for vector input. |
maxDist |
FLOAT |
The orthogonal distance from the line to the point on the shape furthest away from the line, or nil if projection failed. Vector with distances for vector input. |
minDist, maxDist = Shape.getLineDistance(shape, referenceLine)
getLineParameters()
Get the parameters defining the line or line segment. Can only be called for line or line segment shapes (returns nil otherwise). For line segments, the two endpoints are returned. For lines, the first point used to define the line is returned, the second point is one unit distance away from the first point along the line. A vector of line or line segment shapes can be provided, in which case two vectors of parameters are returned.
| Name | Type | Description |
|---|---|---|
line |
CONST_OBJECT Shape |
Input line or line segment shape or vector of line or line segment shapes. |
| Name | Type | Description |
|---|---|---|
point1 |
OBJECT Point |
First line segment endpoint or one point on the line, or vector of points for vector input. |
point2 |
OBJECT Point |
Second line segment endpoint or another point on the line, or vector of points for vector input. |
point1, point2 = Shape.getLineParameters(line)
getPerimeterLength()
Get the length of the perimeter of a shape.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or vector of shapes. |
| Name | Type | Description |
|---|---|---|
perimeterLength |
FLOAT |
Perimeter length, or vector of lengths for vector input. |
perimeterLength = Shape.getPerimeterLength(shape)
getPolylineParameters()
Get the points defining the polyline and a flag indicating if the polyline is closed.
| Name | Type | Description |
|---|---|---|
polyline |
CONST_OBJECT Shape |
The polyline. |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
Vertices for the polyline. |
closed |
BOOL |
If true, the first and last points are connected to form a closed polygon. Otherwise it is an open contour. |
points, closed = Shape.getPolylineParameters(polyline)
getRadius()
Get the radius of the shape. This function is deprecated. Use specific functions for getting the parameters of each Shape instead, for example Shape.getCircleParameters, or the bounding box functions.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape |
| Name | Type | Description |
|---|---|---|
radius |
FLOAT |
Radius of circumscribed circle |
radius = Shape.getRadius(shape)
getRectangleParameters()
Get the parameters defining the rectangle. Can only be called for rectangle shapes (returns nil otherwise). A vector of rectangle shapes can be provided, in which case three vectors of parameters are returned.
| Name | Type | Description |
|---|---|---|
rectangle |
CONST_OBJECT Shape |
Input rectangle shape or vector of rectangle shapes. |
| Name | Type | Description |
|---|---|---|
center |
CONST_OBJECT Point |
Center point (2D) of the rectangle, or vector of center points for vector input. |
width |
FLOAT |
Rectangle width (size along the x axis before rotation), or vector of widths for vector input. |
height |
FLOAT |
Rectangle height (size along the y axis before rotation), or vector of heights for vector input. |
rotation |
FLOAT |
Rectangle rotation in radians. Counter-clockwise rotation in an x/y coordinate system. Vector of rotations for vector input. |
center, width, height, rotationRad = Shape.getRectangleParameters(rectangle)
getSectorParameters()
Get the parameters defining the sector. Can only be called for sector shapes (returns nil otherwise). A vector of sector shapes can be provided, in which case vectors of parameters are returned.
| Name | Type | Description |
|---|---|---|
sector |
CONST_OBJECT Shape |
Input sector shape or vector of sector shapes. |
| Name | Type | Description |
|---|---|---|
center |
OBJECT Point |
Center point of the circle from which the sector is defined, or vector of center points for vector input. |
innerRadius |
FLOAT |
Inner radius of the sector, or vector of inner radii for vector input. |
outerRadius |
FLOAT |
Outer radius of the sector, or vector of outer radii for vector input. |
angleRad |
FLOAT |
Angle where the sector starts, in radians, or vector of angles for vector input. |
deltaAngleRad |
FLOAT |
The angular length of the sector, in radians. Vector of angular lengths for vector input. |
center, innerRadius, outerRadius, angleRad, deltaAngleRad = Shape.getSectorParameters(sector)
getType()
Return the geometric type the Shape represents.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
The shape or shapes to check. |
| Name | Type | Description |
|---|---|---|
shapeType |
ENUM ShapeType |
The shape type or vector with shape types. |
shapeType = Shape.getType(shape)
isClosed()
Check if this is a closed shape. A contour is closed if it has no endpoints and encloses an area. For example, a circle is closed while a line segment is not.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
The shape or shapes to check |
| Name | Type | Description |
|---|---|---|
isClosed |
BOOL |
True if the shape is closed, otherwise false |
isClosed = Shape.isClosed(shape)
rotate()
Rotate the shape. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For arcs and sectors, the nominal center is the center of the base circle. Note on rotation direction: When a shape is used for defining a region in an image, it is interpreted in the left handed coordinate system of the image. In a left-handed system, a positive rotation is in the clockwise direction.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or shapes. |
rotationAngle |
FLOAT |
The rotation angle in radians |
rotationCenter |
CONST_OBJECT Point |
The rotation center. The nominal center of the shape is used if unspecified. |
| Name | Type | Description |
|---|---|---|
outputShape |
OBJECT Shape |
The rotated shape or shapes, or nil if the input shape is invalid. |
outputShape = Shape.rotate(shape, rotationAngle, rotationCenter)
toImage()
Convert the shape into an image, setting pixels within the shape contour to a specific value. The value is in world coordinates and is cropped to the representable range. Pixels outside are set to pixel value zero. Only closed shapes are supported. If several shapes are given, they are all drawn in the same image. Invalid shapes in a list of shapes are ignored.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or vector of shapes. |
referenceImage |
CONST_OBJECT Image |
Reference image, used to define pixel-world mapping. |
worldValue |
FLOAT |
World value to use within the region. Default is 255. |
| Name | Type | Description |
|---|---|---|
outputImage |
OBJECT Image |
Resulting image displaying the shape or nil if not supported. |
outputImage = Shape.toImage(shape,refImage,worldValue)
toLine()
Convert a line segment or a vector of line segments to infinite lines. Only supports line segment input.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Line segment or vector of line segments to convert. |
| Name | Type | Description |
|---|---|---|
line |
OBJECT Shape |
Line or vector of lines created by extending the line segment end points to infinity. |
line = Shape.toLine(lineSegment)
toPixelRegion()
Rasterize a Shape object into a PixelRegion object, using a reference image to define the pixel-world mapping. A vector of shape objects generates a vector of PixelRegion objects.
draw, render, rasterize
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or shapes. |
referenceImage |
CONST_OBJECT Image |
Reference image, used to define pixel-world mapping. |
fill |
BOOL |
Set to true to generate a filled region, false to generate a border region. Non-closed shapes will always generate a border only. Default: true. |
| Name | Type | Description |
|---|---|---|
pixelRegion |
OBJECT Image.PixelRegion |
Pixel region representation of the shape, or a vector of pixel region representations of the shapes. |
pixelRegion = Shape.toPixelRegion(shape, referenceImage)
toPolyline()
Convert this shape to a polyline shape, approximating the true shape if needed (if the true shape is a circle, ellipse or arc). For a shape that is already a polyline, this function can be used to approximate it with a less detailed polyline.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Shape to convert, or vector of shapes. |
epsilon |
FLOAT |
Maximum approximation error in the polyline approximation. |
maxPoints |
INT |
Maximum number of points to use in the approximation (default is 1000). This is a stronger requirement than the epsilon and puts a limit on the function memory usage. |
| Name | Type | Description |
|---|---|---|
polylineShape |
OBJECT Shape |
The shape represented as a polyline, or vector of polylines. |
polylineShape = Shape.toPolyline(shape, epsilon)
toShape3D()
Convert a 2D Shape into the corresponding 3D shape. An optional rigid Transform object may be provided. Without transform, the 3D shape is created in the z=0 plane. The transform is applied after creation, allowing 3D Shapes in other planes. Nil is returned if the input contains invalid shapes or shapes without a corresponding 3D shape.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or vector of shapes. |
transform |
CONST_OBJECT Transform |
Optional transform from the z=0 plane to the desired plane. Must be rigid or less general. |
| Name | Type | Description |
|---|---|---|
outputShape |
OBJECT Shape3D |
The corresponding Shape3D or nil if not supported, or vector of 3D shapes. |
outputShape = Shape.toShape3D(shape, transform)
toString()
Get a human-readable string describing the shape.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape |
| Name | Type | Description |
|---|---|---|
str |
STRING |
String description of the shape |
print(Shape.toString(shape))
transform()
Transform a shape or a vector of shapes. Fails if the transform is not a 2D transform or if the transform would change the underlying shape type.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or shapes. |
transform |
CONST_OBJECT Transform |
Transform to apply. |
| Name | Type | Description |
|---|---|---|
outputShape |
OBJECT Shape |
Transformed shape or shapes, or nil on error. |
outputShape = Shape.transform(shape, transform)
translate()
Translate the shape, i.e., shift it along the x,y-axes. Note on translation direction: When a shape is used for defining a region in an image, it is interpreted in the left handed coordinate system of the image in which the y-axis is pointing downwards. A positive translation therefore shifts the shape downwards when overlaid on top of the image.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input shape or shapes |
translationX |
FLOAT |
The translation along the X-axis |
translationY |
FLOAT |
The translation along the Y-axis |
| Name | Type | Description |
|---|---|---|
outputShape |
OBJECT Shape |
The translated shape or shapes, or nil if the input shape is invalid |
outputShape = Shape.translate(shape, translationX, translationY)
Shape.Composite
Composite of several individual shapes. The composite contains a set of positive shapes and an optional set of negative shapes, and the final shape is the union of all positive shapes, with the union of all negative shapes removed. The order of the shapes has no significance.
Keywords
draw, rasterize, render
See also
Overview
Functions
addShape()
Add a shape to the composite
| Name | Type | Description |
|---|---|---|
composite |
OBJECT Shape.Composite |
The composite to modify |
shape |
CONST_OBJECT Shape |
The shape to add |
isPositive |
BOOL |
True means positive shape, false means negative shape (default is positive) |
Shape.Composite.addShape(composite, shape, isPositive)
clone()
Create an independent deep copy of the composite
| Name | Type | Description |
|---|---|---|
inputComposite |
CONST_OBJECT Shape.Composite |
Input composite |
| Name | Type | Description |
|---|---|---|
outputComposite |
OBJECT Shape.Composite |
Deep copy of the input composite |
sc2 = Shape.Composite.clone(sc)
contains()
Check if the given point is within this composite (within any of the positive shapes but not within any of the negative ones). False is returned if any invalid shape is in the composite.
| Name | Type | Description |
|---|---|---|
composite |
CONST_OBJECT Shape.Composite |
Input composite |
point |
CONST_OBJECT Point |
Point to check |
| Name | Type | Description |
|---|---|---|
result |
BOOL |
True if the point is within the region, otherwise false |
b = Shape.Composite.contains(composite, point)
create()
Create an empty shape composite
| Name | Type | Description |
|---|---|---|
composite |
OBJECT Shape.Composite |
The created shape composite. |
sc = Shape.Composite.create()
getPositiveBoundingBox()
Get a bounding box of all positive shapes. This box is guaranteed to contain the entire region but might not be the tightest possible box if negative regions are used.
| Name | Type | Description |
|---|---|---|
composite |
CONST_OBJECT Shape.Composite |
The composite to use |
| Name | Type | Description |
|---|---|---|
box |
OBJECT Shape |
Rectangle shape representing the bounding box |
box = Shape.Composite.getPositiveBoundingBox(composite)
getShape()
Get one of the shapes and its associated isNegative flag
| Name | Type | Description |
|---|---|---|
composite |
CONST_OBJECT Shape.Composite |
Input shape composite |
index |
INT |
Index of the shape to return (0-based) |
| Name | Type | Description |
|---|---|---|
shape |
OBJECT Shape |
The requested shape |
isPositive |
BOOL |
True if the shape is positive, otherwise false |
shape, isPositive = Shape.Composite.getShape(composite, index)
getShapeCount()
Get the number of shapes contained in this composite
| Name | Type | Description |
|---|---|---|
composite |
CONST_OBJECT Shape.Composite |
Input shape composite |
| Name | Type | Description |
|---|---|---|
count |
INT |
Number of shapes in the composite (positive and negative) |
n = Shape.Composite.getShapeCount(composite)
toImage()
Convert the composite shape into an image, setting pixels within the shape contour to a specific value. The value is in world coordinates and is cropped to the representable range. Pixels outside are set to pixel value zero.
| Name | Type | Description |
|---|---|---|
composite |
CONST_OBJECT Shape.Composite |
Input composite |
referenceImage |
CONST_OBJECT Image |
Image used to define world-pixel coordinate conversion and target resolution |
worldValue |
FLOAT |
World value to use within the region. Default is 255. |
| Name | Type | Description |
|---|---|---|
outputImage |
OBJECT Image |
The converted image |
image = Shape.Composite.toImage(shapeComposite, referenceImage, worldValue)
toPixelRegion()
Convert a shape composite to a pixel region. This is useful for showing the composite in a viewer, or to use the composite region as input to image processing methods.
| Name | Type | Description |
|---|---|---|
composite |
CONST_OBJECT Shape.Composite |
Composite shape region to convert. |
referenceImage |
CONST_OBJECT Image |
Reference image, defines the image world coordinate system. |
| Name | Type | Description |
|---|---|---|
outputRegion |
OBJECT Image.PixelRegion |
Input composite converted to a PixelRegion. |
pixelRegion = Shape.Composite.toPixelRegion(composite, referenceImage)
toPolygons()
Convert the shape composite to a composite consisting only of polygons. All circle and ellipses in the input are approximated by polygons with a given maximum error.
| Name | Type | Description |
|---|---|---|
inputComposite |
CONST_OBJECT Shape.Composite |
Input composite |
epsilon |
FLOAT |
Maximum approximation error. Controls the number of points used in the polygon approximation of ellipses and circles |
maxPoints |
INT |
Maximum number of points to use in the approximation if each polygon (default is 1000). This is a stronger requirement than the epsilon and puts a limit on the function memory usage. |
| Name | Type | Description |
|---|---|---|
outputComposite |
OBJECT Shape.Composite |
Polygon composite shape. |
outputComposite = Shape.Composite.toPolygons(inputComposite, epsilon)
toString()
Gets a user-friendly string description of the composite shape.
| Name | Type | Description |
|---|---|---|
composite |
CONST_OBJECT [API:DataFormat:] |
The composite shape to describe. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the composite shape . |
str = Shape.Composite.toString(composite)
transform()
Transform the composite according to a general 2D transformation. Requires that all individual shapes support the transformation. For example, if one of the shapes is a circle and the transformation is an affine transformation, the operation will fail, since circles are no longer circles after an affine transformation. For transforming any kind of composite, consider converting the composite to a polygon representation using toPolygons first.
| Name | Type | Description |
|---|---|---|
composite |
CONST_OBJECT Shape.Composite |
Input shape composite |
transform |
CONST_OBJECT Transform |
The transform to use (must be a 2D transform) |
| Name | Type | Description |
|---|---|---|
newComposite |
OBJECT Shape.Composite |
The transformed shape composite |
newComposite = Shape.Composite.transform(composite, transform)
Shape3D
A 3D geometric primitive, e.g., Line, LineSegment, Polyline, Plane, Rectangle, Circle, Box, Sphere, Cylinder, Cone, etc. The pose (position and orientation) of most shapes is controlled by a 3D Transform. Such shapes have a defined default pose, often centered around the origin, from which the pose transform is used to move and rotate the shape into the desired pose in 3D space. When creating a shape, the pose transform is not allowed to change the size of the shape (the size is set by specific parameters), that is, the pose transform must be of rigid, rotation or translation type. Shapes can be transformed using more general transformations, however the type of transformations allowed is specific to each shape and limited to make sure the shape stays within its class. For example, a non-uniform scaling will turn a circle into an ellipse and is thus not allowed. The Shape3D object is represented in mathematical analytical form. Operations such as finding intersection points, distances and transforming the geometric primitive are for this reason efficiently computed.
Overview
clone(), contains(), countInside(), createBox(), createCircle(), createCone(), createCylinder(), createEllipse(), createEllipticCylinder(), createLine(), createLineSegment(), createPlane(), createPlaneFromPoints(), createPolygon(), createPolyline(), createRectangle(), createSphere(), cropLine(), fitLine(), fitPlane(), getArea(), getBoundingBox(), getBounds(), getBoxParameters(), getCenterOfGravity(), getCircleParameters(), getClosestSurfacePoint(), getConeApex(), getConeParameters(), getCylinderParameters(), getEllipseParameters(), getEllipticCylinderParameters(), getIntersectionAngle(), getIntersectionLine(), getIntersectionPoints(), getLineParameters(), getLineSegmentParameters(), getPlaneDistance(), getPlaneParameters(), getPlanePoints(), getPolygonParameters(), getPolylineParameters(), getRectangleParameters(), getSphereParameters(), getType(), getVolume(), isClosed(), isZeroVolume(), projectZ(), rotateX(), rotateY(), rotateZ(), toLine(), toPixelRegion(), toPlane(), toPolygon(), toString(), transform(), translate()
Functions
clone()
Create an independent copy of the shape. If the input is a vector of shapes, the output is a vector of shapes.
| Name | Type | Description |
|---|---|---|
inputShape |
CONST_OBJECT Shape3D |
The shape to clone. |
| Name | Type | Description |
|---|---|---|
outputShape |
OBJECT Shape3D |
The new copy. |
outputShape = Shape3D.clone(inputShape)
contains()
Returns true if the supplied 3D point is within the shape. Returns false for all shapes with zero volume. If more than one shape is provided true is returned if the point is inside any of the shapes. If more than one point is provided a vector is returned with one value for each input point.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
point |
CONST_OBJECT Point |
The 3D point to probe. |
| Name | Type | Description |
|---|---|---|
isInside |
BOOL |
True if the point is inside the shape. |
isInside = Shape3D.contains(shape3d, point)
countInside()
Counts the number of points that fall within the shape.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
points |
CONST_OBJECT Point |
The 3D points to probe. |
| Name | Type | Description |
|---|---|---|
count |
INT |
The number of points within the shape. |
count = Shape3D.countInside(shape3d, points)
createBox()
Create a box in 3D space. Unless transformed, the box is centered on the origin.
| Name | Type | Description |
|---|---|---|
sizeX |
FLOAT |
Size of the box in the x-direction before transformation. |
sizeY |
FLOAT |
Size of the box in the y-direction before transformation. |
sizeZ |
FLOAT |
Size of the box in the z-direction before transformation. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the box position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform. |
| Name | Type | Description |
|---|---|---|
box |
OBJECT Shape3D |
The created box. |
box = Shape3D.createBox(sizeX, sizeY, sizeZ, poseTransform)
createCircle()
Create a 2D circle embedded in 3D space. Unless transformed, the circle is created in the xy-plane, centered on the origin.
| Name | Type | Description |
|---|---|---|
radius |
FLOAT |
Radius of the circle. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the circle position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform. |
| Name | Type | Description |
|---|---|---|
circle |
OBJECT Shape3D |
The created 3D circle. |
circle = Shape3D.createCircle(radius, poseTransform)
createCone()
Create a cone in 3D space. Unless transformed, the z-axis is the symmetry axis of the cone, the base circle is centered on the origin and the apex is at the point (0, 0, heightZ).
| Name | Type | Description |
|---|---|---|
radius |
FLOAT |
Largest radius of the cone. |
heightZ |
FLOAT |
Height of the cone in the z-direction before transformation. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the cone position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform. |
| Name | Type | Description |
|---|---|---|
cone |
OBJECT Shape3D |
The created cone. |
cone = Shape3D.createCone(radius, heightZ, poseTransform)
createCylinder()
Create a cylinder in 3D space. Unless transformed, the cylinder is centered on the origin with the z-axis as symmetry line.
| Name | Type | Description |
|---|---|---|
radius |
FLOAT |
Radius in the xy-plane before transformation. |
heightZ |
FLOAT |
Height of the cylinder in the z-direction before transformation. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the cylinder position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform. |
| Name | Type | Description |
|---|---|---|
cylinder |
OBJECT Shape3D |
The created cylinder. |
cylinder = Shape3D.createCylinder(radius, heightZ, poseTransform)
createEllipse()
Create a 2D ellipse embedded in 3D space. Unless transformed, the ellipse is created in the xy-plane, centered on the origin.
| Name | Type | Description |
|---|---|---|
radiusX |
FLOAT |
Radius of the ellipse in the x-direction before transformation. |
radiusY |
FLOAT |
Radius of the ellipse in the y-direction before transformation. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the ellipse position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform. |
| Name | Type | Description |
|---|---|---|
ellipse |
OBJECT Shape3D |
The created 3D ellipse. |
ellipse = Shape3D.createEllipse(radiusX, radiusY, poseTransform)
createEllipticCylinder()
Create an elliptic cylinder in 3D space. Unless transformed, the elliptic cylinder is centered on the origin centered on the z-axis.
| Name | Type | Description |
|---|---|---|
radiusX |
FLOAT |
Radius in the x-direction before transformation. |
radiusY |
FLOAT |
Radius in the y-direction before transformation. |
heightZ |
FLOAT |
Height of the elliptic cylinder in the z-direction before transformation. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the elliptic cylinder position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform. |
| Name | Type | Description |
|---|---|---|
ellipticCylinder |
OBJECT Shape3D |
The created elliptic cylinder. |
ellipticCylinder = Shape3D.createEllipticCylinder(radiusX, radiusY, heightZ, poseTransform)
createLine()
Create a line in 3D, passing through the two given 3D points.
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
First 3D point on the line. |
point2 |
CONST_OBJECT Point |
Second 3D point on the line. |
| Name | Type | Description |
|---|---|---|
line |
OBJECT Shape3D |
The created 3D line, or nil if the two point coincide. |
line = Shape3D.createLine(point1, point2)
createLineSegment()
Create a line segment in 3D between the two given 3D points.
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
First 3D endpoint of the line segment. |
point2 |
CONST_OBJECT Point |
Second 3D endpoint of the line segment. |
| Name | Type | Description |
|---|---|---|
lineSegment |
OBJECT Shape3D |
The created 3D line segment, or nil if the two point coincide. |
lineSegment = Shape3D.createLineSegment(point1, point2)
createPlane()
Create a plane in 3D. A plane is defined by its normal vector (vector perpendicular to the plane) and a distance from the world origin (Hesse normal form). For example, an XY-aligned plane at Z = 5 is constructed using Shape3D.createPlane(0, 0, 1, 5). The distance is signed and measured from the origin along the normal. A plane where the normal points from the plane towards the origin has a negative distance.
| Name | Type | Description |
|---|---|---|
nx |
FLOAT |
X component of plane normal vector. |
ny |
FLOAT |
Y component of plane normal vector. |
nz |
FLOAT |
Z component of plane normal vector. |
distance |
FLOAT |
Distance from the origin to the plane along the plane normal. |
| Name | Type | Description |
|---|---|---|
plane |
OBJECT Shape3D |
The created plane, or nil if the normal vector was a zero vector. |
plane = Shape3D.createPlane(nx, ny, nz, distance)
createPlaneFromPoints()
Create a plane in 3D containing the three given 3D points. The three points must span a plane, i.e., they must not be distributed along a line.
| Name | Type | Description |
|---|---|---|
point1 |
CONST_OBJECT Point |
First 3D point. |
point2 |
CONST_OBJECT Point |
Second 3D point. |
point3 |
CONST_OBJECT Point |
Third 3D point. |
| Name | Type | Description |
|---|---|---|
plane |
OBJECT Shape3D |
The created plane, or nil if the points are in a degenerate configuration. |
plane = Shape3D.createPlaneFromPoints(point1, point2, point3)
createPolygon()
Create a 2D closed polygon embedded in 3D space. If the points are not in a plane, the points are projected onto the best fitting plane. At least three points are required.
| Name | Type | Description |
|---|---|---|
points |
CONST_OBJECT Point |
Corner points for the polygon. |
| Name | Type | Description |
|---|---|---|
polygon |
OBJECT Shape3D |
The created 2D polygon in 3D. |
polygon = Shape3D.createPolygon(points)
createPolyline()
Create a full 3D polyline. Corners can be placed freely in 3D, however, a closed surface for a general 3D polyline would be ambiguous and thus this shape can not be closed. Use the 3D polygon for closed shapes.
| Name | Type | Description |
|---|---|---|
points |
CONST_OBJECT Point |
Corner points for the polyline. |
| Name | Type | Description |
|---|---|---|
polyline |
OBJECT Shape3D |
The created polyline. |
polyline = Shape3D.createPolyline(points)
createRectangle()
Create a 2D rectangle embedded in 3D space. Unless transformed, the rectangle is created in the xy-plane, centered on the origin.
| Name | Type | Description |
|---|---|---|
sizeX |
FLOAT |
Size of the rectangle in the x-direction before transformation (width). |
sizeY |
FLOAT |
Size of the rectangle in the y-direction before transformation (height). |
poseTransform |
CONST_OBJECT Transform |
Transform defining the rectangle position and orientation in 3D space. Must be of type identity, translation or rigid. Optional, default is an identity transform. |
| Name | Type | Description |
|---|---|---|
rectangle |
OBJECT Shape3D |
The created 3D rectangle. |
rectangle = Shape3D.createRectangle(sizeX, sizeY, poseTransform)
createSphere()
Create a sphere in 3D space. Unless transformed, the sphere is centered on the origin.
| Name | Type | Description |
|---|---|---|
radius |
FLOAT |
Radius of the sphere. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the sphere position and orientation in 3D space. Must be of type identity, translation or rigid. The sphere itself is invariant to rotations however the orientation of the local coordinate system is affected. Optional, default is an identity transform. |
| Name | Type | Description |
|---|---|---|
sphere |
OBJECT Shape3D |
The created sphere. |
sphere = Shape3D.createSphere(radius, poseTransform)
cropLine()
Returns the part of a line within a box as a new line segment. If the line does not intersect the box, nil is returned.
| Name | Type | Description |
|---|---|---|
line |
CONST_OBJECT Shape3D |
The line shape to be cropped. |
box |
CONST_OBJECT Shape3D |
The box to crop the line with. |
| Name | Type | Description |
|---|---|---|
line |
OBJECT Shape3D |
The part of the line within the box as a line segment. |
lineSegment = Shape3D.cropLine(line, box)
fitLine()
Fit a 3D line to a set of 3D-points. Different fitting and outlier handling modes are available. Fitting mode may be any of: LEASTSQUARES - Ordinary least squares, fast but not robust against outliers. RANSAC - Outlier rejection by random sampling and consensus. The trade-off between speed and robustness can be adjusted using an iteration parameter. TRIMMED - Two stages of least squares fitting with outlier rejection between the stages. Performance is in general in between RANSAC and least squares with respect to robustness and speed. For RANSAC and trimmed modes, outliers are specified with a margin parameter in one of the following ways: ABSOLUTE - Absolute outlier margin, points with a distance larger than the specified distance from the line are treated as outliers. RANK - Defines the fraction of points to treat as inlier points. For example, a rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored as outliers. If there are additional points close to the margin, those will also be included such that the final inlier fraction may be higher.
| Name | Type | Description |
|---|---|---|
points |
CONST_OBJECT Point |
Input points. |
mode |
Fitting mode. Default is LEASTSQUARES. |
|
marginType |
Outlier margin type (ABSOLUTE or RANK). Only used in fitting modes: RANSAC and TRIMMED. Default is ABSOLUTE. |
|
margin |
FLOAT |
Inlier margin, the interpretation depends on the margin type. Only used in iterative fitting modes: RANSAC and TRIMMED. Default is 2.0 for ABSOLUTE and 0.5 for RANK. |
iterations |
INT |
Number of iterations. Only used in iterative fitting mode: RANSAC. |
| Name | Type | Description |
|---|---|---|
line |
OBJECT Shape3D |
The 3D line with best fit. |
quality |
FLOAT |
Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the line. |
line3d, quality = Shape3D.fitLine(points, mode, margin, iterations)
fitPlane()
Fit a plane shape to a set of 3D-points. Different fitting and outlier handling modes are available. Fitting mode may be any of: LEASTSQUARES - Ordinary least squares, fast but not robust against outliers. RANSAC - Outlier rejection by random sampling and consensus. The trade-off between speed and robustness can be adjusted using an iteration parameter. TRIMMED - Two stages of least squares fitting with outlier rejection between the stages. Performance is in general in between RANSAC and least squares with respect to robustness and speed. For RANSAC and trimmed modes, outliers are specified with a margin parameter in one of the following ways: ABSOLUTE - Absolute outlier margin, points with a distance larger than the specified distance from the plane are treated as outliers. RANK - Defines the fraction of points to treat as inlier points. For example, a rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored as outliers. If there are additional points close to the margin, those will also be included such that the final inlier fraction may be higher.
| Name | Type | Description |
|---|---|---|
points |
CONST_OBJECT Point |
Input points. |
mode |
Fitting mode. Default is LEASTSQUARES. |
|
marginType |
Outlier margin type (ABSOLUTE or RANK). Only used in fitting modes: RANSAC and TRIMMED. Default is ABSOLUTE. |
|
margin |
FLOAT |
Inlier margin, the interpretation depends on the margin type. Only used in fitting modes: RANSAC and TRIMMED. Default is 2.0 for ABSOLUTE and 0.5 for RANK. |
iterations |
INT |
Number of iterations. Only used in iterative fitting mode: RANSAC. Default is 20. |
| Name | Type | Description |
|---|---|---|
plane |
OBJECT Shape3D |
Plane with best fit. |
quality |
FLOAT |
Vector with fitting quality measurements [meanError, inlierRate], where meanError is the average fitting error of inlier points in world coordinates and inlierRate is the rate of input points that were accepted as belonging to the plane. |
plane, quality = Shape3D.fitPlane(points, mode, margin, iterations)
getArea()
Returns the total surface area of the shape. For flat shapes, e.g., a rectangle, circle or ellipse in 3D space, only one side is counted.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
| Name | Type | Description |
|---|---|---|
area |
FLOAT |
The surface area of the shape. |
area = Shape3D.getArea(shape3d)
getBoundingBox()
Returns the smallest axis aligned box that encloses the shape.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
| Name | Type | Description |
|---|---|---|
boundingBox |
OBJECT Shape3D |
The axis aligned bounding box of the shape. |
boundingBox = Shape3D.getBoundingBox(shape3d)
getBounds()
Get the bounds of the shape as individual values.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape3D |
Input shape |
| Name | Type | Description |
|---|---|---|
xMin |
FLOAT |
Minimum x coordinate. |
yMin |
FLOAT |
Minimum y coordinate. |
zMin |
FLOAT |
Minimum z coordinate. |
xMax |
FLOAT |
Maximum x coordinate. |
yMax |
FLOAT |
Maximum y coordinate. |
zMax |
FLOAT |
Maximum z coordinate. |
xMin, yMin, zMin, xMax, yMax, zMax = Shape3D.getBounds(shape)
getBoxParameters()
Get the size and pose of the 3D box.
| Name | Type | Description |
|---|---|---|
box |
CONST_OBJECT Shape3D |
The created box. |
| Name | Type | Description |
|---|---|---|
sizeX |
FLOAT |
Size of the box in the x-direction before transformation. |
sizeY |
FLOAT |
Size of the box in the y-direction before transformation. |
sizeZ |
FLOAT |
Size of the box in the z-direction before transformation. |
poseTransform |
OBJECT Transform |
Transform defining the box position and orientation in 3D space. Is of type identity, translation or rigid. |
sizeX, sizeY, sizeZ, poseTransform = Shape3D.getBoxParameters(box)
getCenterOfGravity()
Returns the center of gravity of the shape. Returns nil for invalid shapes and for shapes with infinite size.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
| Name | Type | Description |
|---|---|---|
center |
OBJECT Point |
The center of gravity of the shape. |
center = Shape3D.getCenterOfGravity(shape3d)
getCircleParameters()
Get the radius and pose of the 3D circle.
| Name | Type | Description |
|---|---|---|
circle |
OBJECT Shape3D |
The 3D circle. |
| Name | Type | Description |
|---|---|---|
radius |
FLOAT |
Radius of the circle. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the circle position and orientation in 3D space. Is of type identity, translation or rigid. |
radius, poseTransform = Shape3D.getCircleParameters(circle)
getClosestSurfacePoint()
Returns the point on the shape surface (or edge) closest to the probe point. If there are more than one shape provided the closest point on any shape surface is returned. If there are more than one point provided one point is returned for each input point.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
point |
CONST_OBJECT Point |
The 3D point to probe. |
| Name | Type | Description |
|---|---|---|
surfacePoint |
OBJECT Point |
The point on the surface closest to the probe point. |
distance |
FLOAT |
The distance to the closest point. |
surfacePoint = Shape3D.getClosestSurfacePoint(shape3d, point)
getConeApex()
Returns the position of the tip of the cone. Together with getCenterOfGravity, two points defining the direction of the cone can be found.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape3D |
The cone. |
| Name | Type | Description |
|---|---|---|
apex |
OBJECT Point |
The apex of the cone, or nil if any other shape is given. |
apex = Shape3D.getConeApex(shape)
getConeParameters()
Get the radius, height and pose of a cone.
| Name | Type | Description |
|---|---|---|
cone |
OBJECT Shape3D |
The cone. |
| Name | Type | Description |
|---|---|---|
radius |
FLOAT |
The largest radius of the cone. |
heightZ |
FLOAT |
Height of the cone from the base circle to the apex. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the cone position and orientation in 3D space. Is of type identity, translation or rigid. |
radius, heightZ, poseTransform = Shape3D.getConeParameters(cone)
getCylinderParameters()
Get the radius, height and pose of a cylinder.
| Name | Type | Description |
|---|---|---|
cylinder |
OBJECT Shape3D |
The created cylinder. |
| Name | Type | Description |
|---|---|---|
radius |
FLOAT |
Radius in the xy-plane before transformation. |
heightZ |
FLOAT |
Height of the cylinder in the z-direction before transformation. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the cylinder position and orientation in 3D space. Is of type identity, translation or rigid. |
radius, heightZ, poseTransform = Shape3D.getCylinderParameters(cylinder)
getEllipseParameters()
Get the radii and pose transform of the 3D ellipse.
| Name | Type | Description |
|---|---|---|
ellipse |
OBJECT Shape3D |
The 3D ellipse. |
| Name | Type | Description |
|---|---|---|
radiusX |
FLOAT |
Radius of the ellipse in the x-direction before transformation. |
radiusY |
FLOAT |
Radius of the ellipse in the y-direction before transformation. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the ellipse position and orientation in 3D space. Is of type identity, translation or rigid. |
radiusX, radiusY, poseTransform = Shape3D.getEllipseParameters(ellipse)
getEllipticCylinderParameters()
Get the radii, height and pose of an elliptic cylinder.
| Name | Type | Description |
|---|---|---|
ellipticCylinder |
OBJECT Shape3D |
The elliptic cylinder. |
| Name | Type | Description |
|---|---|---|
radiusX |
FLOAT |
Radius in the x-direction before transformation. |
radiusY |
FLOAT |
Radius in the y-direction before transformation. |
heightZ |
FLOAT |
Height of the elliptic cylinder in the z-direction before transformation. |
poseTransform |
CONST_OBJECT Transform |
Transform defining the elliptic cylinder position and orientation in 3D space. Is of type identity, translation or rigid. |
radiusX, radiusY, heightZ, poseTransform = Shape3D.getEllipticCylinderParameters(ellipticCylinder)
getIntersectionAngle()
Get the sharpest angle between two flat Shape3D shapes (circle, rectangle, ellipse in 3D space, etc.), 3D lines, 3D line segments or combination thereof. The shapes do not need to intersect. The angle is in the range 0 to pi/2 where zero indicates parallel planes or lines. Shapes lying in orthogonal planes result in the angle pi/2. Nil is returned if either argument is not a flat shape or a line.
| Name | Type | Description |
|---|---|---|
shape1 |
CONST_OBJECT Shape3D |
Shape 1, a flat shape, line or line segment. |
shape2 |
CONST_OBJECT Shape3D |
Shape 2, a flat shape, line or line segment. |
| Name | Type | Description |
|---|---|---|
angle |
FLOAT |
Sharpest angle between shapes, or Nil if shapes are not flat. |
angle = Shape3D.getIntersectionAngle(shape1, shape2)
getIntersectionLine()
Returns the intersection line of two planes.
| Name | Type | Description |
|---|---|---|
shape1 |
CONST_OBJECT Shape3D |
First plane. |
shape2 |
CONST_OBJECT Shape3D |
Second plane. |
| Name | Type | Description |
|---|---|---|
intersections |
OBJECT Shape3D |
Intersection line. If there is no intersection, an empty list is returned. If the shape combination is not supported, nil is returned. |
intersections = Shape3D.getIntersectionLine(shape1, shape2)
getIntersectionPoints()
Returns the intersection points of two shapes. One of the shapes must be a line or a line segment.
| Name | Type | Description |
|---|---|---|
shape1 |
CONST_OBJECT Shape3D |
First shape. |
shape2 |
CONST_OBJECT Shape3D |
Second shape. |
| Name | Type | Description |
|---|---|---|
intersections |
OBJECT Point |
Intersection points. If there are intersections, an empty list is returned. If the shape combination is not supported, nil is returned. |
intersections = Shape3D.getIntersectionPoints(shape1, shape2)
getLineParameters()
Get two 3D points on the line. Note that these two points may not be the same points used for creating a line using the createLine() function as the line representation is normalized internally.
| Name | Type | Description |
|---|---|---|
line |
CONST_OBJECT Shape3D |
The 3D line. |
| Name | Type | Description |
|---|---|---|
point1 |
OBJECT Point |
First 3D point on the line. |
point2 |
OBJECT Point |
Second 3D point on the line. |
point1, point2 = Shape3D.getLineParameters(line)
getLineSegmentParameters()
Get the 3D end points of the line segment.
| Name | Type | Description |
|---|---|---|
lineSegment |
CONST_OBJECT Shape3D |
The 3D line segment. |
| Name | Type | Description |
|---|---|---|
point1 |
OBJECT Point |
First 3D endpoint on the line segment. |
point2 |
OBJECT Point |
Second 3D endpoint on the line segment. |
point1, point2 = Shape3D.getLineSegmentParameters(lineSegment)
getPlaneDistance()
Returns the minimum and maximum distance from all points on the shape to the reference plane. Distances are measured orthogonal to the reference plane. The query shape should have finite size.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape3D |
The shape to check distance to. |
referencePlane |
CONST_OBJECT Shape3D |
The reference plane. |
| Name | Type | Description |
|---|---|---|
minDist |
FLOAT |
The distance from the plane to the closest point on the shape, or nil if projection failed. |
maxDist |
FLOAT |
The orthogonal distance from the plane to the point on the shape furthest away from the plane, or nil if projection failed. |
minDist, maxDist = Shape3D.getPlaneDistance(shape, referencePlane)
getPlaneParameters()
Get the parameters of the plane (normal vector plus distance). The distance is signed and measured from the origin along the normal. A plane where the normal points from the plane towards the origin has a negative distance.
| Name | Type | Description |
|---|---|---|
plane |
CONST_OBJECT Shape3D |
The plane. |
| Name | Type | Description |
|---|---|---|
nx |
FLOAT |
X component of plane normal vector. |
ny |
FLOAT |
Y component of plane normal vector. |
nz |
FLOAT |
Z component of plane normal vector. |
distance |
FLOAT |
Distance from the origin to the plane along the plane normal. |
nx, ny, nz, distance = Shape3D.getPlaneParameters(plane)
getPlanePoints()
Returns the point(s) on the plane at the given x,y-coordinate(s).
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape |
Input plane. |
points2d |
CONST_OBJECT Point |
Query points. |
| Name | Type | Description |
|---|---|---|
points3d |
OBJECT Point |
Points on plane, nil if any error occurred. |
points3d = Shape3D.getPlanePoints(shape, points2d)
getPolygonParameters()
Get the points defining the polygon.
| Name | Type | Description |
|---|---|---|
polygon |
CONST_OBJECT Shape3D |
The polygon. |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
Corner points for the polygon. |
points = Shape3D.getPolygonParameters(polygon)
getPolylineParameters()
Get the points defining the polyline.
| Name | Type | Description |
|---|---|---|
polyline |
CONST_OBJECT Shape3D |
The polyline. |
| Name | Type | Description |
|---|---|---|
points |
OBJECT Point |
Corner points for the polyline. |
points = Shape3D.getPolylineParameters(polyline)
getRectangleParameters()
Get the size and pose of the 3D rectangle.
| Name | Type | Description |
|---|---|---|
rectangle |
CONST_OBJECT Shape3D |
The 3D rectangle. |
| Name | Type | Description |
|---|---|---|
sizeX |
FLOAT |
Size of the rectangle in the x-direction before transformation (width). |
sizeY |
FLOAT |
Size of the rectangle in the y-direction before transformation (height). |
poseTransform |
OBJECT Transform |
Transform defining the rectangle position and orientation in 3D space. Is of type identity, translation or rigid. |
sizeX, sizeY, poseTransform = Shape3D.getRectangleParameters(rectangle)
getSphereParameters()
Get the radius and position of the sphere.
| Name | Type | Description |
|---|---|---|
sphere |
CONST_OBJECT Shape3D |
The sphere. |
| Name | Type | Description |
|---|---|---|
radius |
FLOAT |
Radius of the sphere. |
poseTransform |
OBJECT Transform |
Transform defining the sphere position and orientation in 3D space. Is of type identity, translation or rigid. |
radius, poseTransform = Shape3D.getSphereParameters(sphere)
getType()
Get the shape type.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
| Name | Type | Description |
|---|---|---|
shapeType |
ENUM Shape3DType |
The shape type. |
shapeType = Shape3D.getType(shape3d)
getVolume()
Returns the volume of the shape.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
| Name | Type | Description |
|---|---|---|
volume |
FLOAT |
The volume of the shape. |
volume = Shape3D.getVolume(shape3d)
isClosed()
Returns true if the shape has no endpoints and encloses an area.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
| Name | Type | Description |
|---|---|---|
closed |
BOOL |
True if the shape is closed. |
closed = Shape3D.isClosed(shape3d)
isZeroVolume()
Returns true if the shape type in general has no volume, such as for 2D shapes in 3D space.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
| Name | Type | Description |
|---|---|---|
noVolume |
BOOL |
True if the shape has zero volume. |
noVolume = Shape3D.isZeroVolume(shape3d)
projectZ()
Projects one or more Shape3D orthogonally onto the plane described by z = 0. Returns the result as one or more Shape2D together with the minimum and maximum z-values encountered. Lines, line segments, circles, ellipses, boxes, rectangles, spheres, polygons and polylines are supported.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape3D |
Shape(s) to be projected. |
| Name | Type | Description |
|---|---|---|
projectedShape |
OBJECT Shape |
The projected shape(s), or nil if projection failed. |
zMin |
FLOAT |
Minimum z-value(s) of shape(s) before projection, or nil if projection failed. |
zMax |
FLOAT |
Maximum z-value(s) of shape(s) before projection, or nil if projection failed. |
projectedShape, zMin, zMax = Shape3D.projectZ(shape)
rotateX()
Rotate the shape around an axis parallel to the world x-axis. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For cones, the nominal center is the center of the base circle. For lines and planes, the nominal center is the point in the shape closest to the origin.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape3D |
Input shape |
rotationAngle |
FLOAT |
The rotation angle in radians |
rotationCenter |
CONST_OBJECT Point |
The rotation center. The nominal center of the shape is used if unspecified. |
| Name | Type | Description |
|---|---|---|
outputShape |
OBJECT Shape3D |
The rotated shape, or nil if the input shape is invalid. |
outputShape = Shape3D.rotateX(shape, rotationAngle, rotationCenter)
rotateY()
Rotate the shape around an axis parallel to the world y-axis. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For cones, the nominal center is the center of the base circle. For lines and planes, the nominal center is the point in the shape closest to the origin.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape3D |
Input shape |
rotationAngle |
FLOAT |
The rotation angle in radians |
rotationCenter |
CONST_OBJECT Point |
The rotation center. The nominal center of the shape is used if unspecified. |
| Name | Type | Description |
|---|---|---|
outputShape |
OBJECT Shape3D |
The rotated shape, or nil if the input shape is invalid. |
outputShape = Shape3D.rotateY(shape, rotationAngle, rotationCenter)
rotateZ()
Rotate the shape around an axis parallel to the world z-axis. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For cones, the nominal center is the center of the base circle. For lines and planes, the nominal center is the point in the shape closest to the origin.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape3D |
Input shape |
rotationAngle |
FLOAT |
The rotation angle in radians |
rotationCenter |
CONST_OBJECT Point |
The rotation center. The nominal center of the shape is used if unspecified. |
| Name | Type | Description |
|---|---|---|
outputShape |
OBJECT Shape3D |
The rotated shape, or nil if the input shape is invalid. |
outputShape = Shape3D.rotateZ(shape, rotationAngle, rotationCenter)
toLine()
Extends a line segment to the the infinite line type.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
A line segment 3D shape. |
| Name | Type | Description |
|---|---|---|
line |
OBJECT Shape3D |
The extended shape as a line. |
line = Shape3D.toLine(shape3d)
toPixelRegion()
Projects the convex hull of a Shape3D (except polyLine) onto the plane z = 0 (in world coordinates) and creates the corresponding pixel region. The minimum and maximum world coordinate extent of the convex hull in the z-direction are returned. The reference image defines the pixel coordinate system to be used for the PixelRegion.
draw, project, render, rasterize
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape3D |
The shape used to define the pixel region. |
referenceImage |
CONST_OBJECT Image |
An image defining the coordinate system used to create the PixelRegion. |
fill |
BOOL |
Set to true to generate a filled region, false to generate a border region. Non-closed shapes will always generate a border only. |
| Name | Type | Description |
|---|---|---|
pixelRegion |
OBJECT Image.PixelRegion |
The projected convex hull region, or nil on error. |
zMin |
FLOAT |
The minimum z-position of any part of the shape, in image world coordinates. |
zMax |
FLOAT |
The maximum z-position of any part of the shape, in image world coordinates. |
pixelRegion, zMin, zMax = Shape3D.toPixelRegion(shape, referenceImage)
toPlane()
Returns the plane which a flat shape span, such as rectangles, circles and polygons. Not defined for a line type shape.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
A flat 3D shape input. |
| Name | Type | Description |
|---|---|---|
plane |
OBJECT Shape3D |
The plane containing the flat 3D shape. |
plane = Shape3D.toPlane(shape3d)
toPolygon()
Approximates a flat closed shape in 3D as a polygon.
| Name | Type | Description |
|---|---|---|
shape |
CONST_OBJECT Shape3D |
Shape to be approximated. |
epsilon |
FLOAT |
Maximum approximation error in the polygon approximation. |
maxPoints |
INT |
Maximum number of points to use in the approximation (default is 1000). This is a stronger requirement than the epsilon and puts a limit on the function memory usage. |
| Name | Type | Description |
|---|---|---|
polygon |
OBJECT Shape3D |
The shape as a polygon, or nil if the shape is invalid or non-flat. |
polygon = Shape3D.toPolygon(shape, epsilon, maxPoints)
toString()
Get a user-friendly string description of the 3D shape.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly string description. |
print(Shape3D.toString(shape3d))
transform()
Transforms a single shape or a vector of shapes according to the supplied transform. The transform must not change the type of the geometric primitive, e.g., it is not possible to transform a sphere using an affine transform as the result may not be a sphere anymore. The pose transform of shapes are kept as non-mirroring rigid transforms, made to always generate a right-handed orthonormal local coordinate system. Transforming a shape with a similarity transform will decompose the transform and apply the scaling component directly to the size of the shape. Similarly, a transform containing a mirroring component will be reformulated to get the mirroring aligned with a symmetry plane of the shape, where it has no effect on the shape and will be removed. Thus the shape will be correctly transformed, however fetching the pose transform of a shape may not return the transform used to transform the shape.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
transform |
CONST_OBJECT Transform |
The transform to apply. |
| Name | Type | Description |
|---|---|---|
transformedShape |
OBJECT Shape3D |
The transformed shape. |
transformedShape = Shape3D.transform(shape3d, transform)
translate()
Translate the shape, i.e., shift it along the x,y,z directions.
| Name | Type | Description |
|---|---|---|
shape3d |
CONST_OBJECT Shape3D |
3D shape input. |
translationX |
FLOAT |
The translation along the X-axis. |
translationY |
FLOAT |
The translation along the Y-axis. |
translationZ |
FLOAT |
The translation along the Z-axis. |
| Name | Type | Description |
|---|---|---|
outputShape |
OBJECT Shape3D |
The translated shape, or nil if the input shape is invalid. |
outputShape = Shape3D.translate(shape3d, translationX, translationY, translationZ)
Statistics
Functions for computing statistics of 1D numeric arrays, signals, time series, histograms etc. For example mean, standard deviation, correlation, comparing histograms. More functions for 1D data analysis is under the Profile API.
See also
Overview
Functions
compareHistograms()
Compare two histograms of equal size. If the histograms are obtained from regions of different sizes, they should be normalized first.
| Name | Type | Description |
|---|---|---|
histogram1 |
FLOAT |
First histogram to compare |
histogram2 |
FLOAT |
Second histogram to compare |
method |
Comparison method (default is Chi-squared statistic) |
| Name | Type | Description |
|---|---|---|
distance |
FLOAT |
Distance measure of the two histograms. Zero if they are equal and larger the more different the histograms are. |
distance = Statistics.compareHistograms(histogram1, histogram2)
normalizeHistogram()
Normalize a histogram. If no bin centers are specified, the histogram is normalized such that the sum of all values is 1. If centers is specified, it is instead normalized such that the integral over the value domain is 1.
| Name | Type | Description |
|---|---|---|
inputHistogram |
FLOAT |
Input histogram |
centers |
FLOAT |
Optional bin centers. Must be equally spaced. Typically, the bin centers are returned from the method that produced the histogram in the first place. |
| Name | Type | Description |
|---|---|---|
outputHistogram |
FLOAT |
Output histogram, normalized to unit sum |
outputHistogram = Statistics.normalizeHistogram(inputHistogram)
TCPIPClient
Provides raw TCIP/IP connections to servers. First a new TCPIPClient needs to be created using the create function. Afterwards the IP address and the port must be set using the set-functions. Then a call to the connect-function starts the connection tries to the server. If the connection gets disconnected it is tried to established it again automatically. Connects and disconnects can be detected by a register to the OnConnect and OnDisconnect events or by polling the IsConnected function. Failed transmits are a sign of broken connection and user could also call disconnect manually. Data could be transmitted to the server using the "transmit" function. Data could be received by a register to the "OnReceive" event or by calling the blocking receive()-function. The transmitted and received data is raw data. It could get automatically framed for transmitting and receiving can be automatically parsed if setting a framing with the "setFraming" function. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.
Keywords
Ethernet
See also
Overview
Functions
connect()
Starts trying to connect to the server. The OnConnected and OnDisconnected events are thrown every time the connection gets connected or disconnected. If the client gets disconnected, the client automatically tries to reconnect every 5 seconds in the background. So the connect function does not need to be called in OnDisconnect.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
timeoutMs |
INT |
The timeout to wait initially until the client gets connected. If not set, 500ms is the default. Check IsConnected afterwards if was successful. |
TCPIPClient.connect(handle)
create()
Creates a new TCP/IP client instance. Client stays active as long as this handle exists.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
handle = TCPIPClient.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
disconnect()
Forces a disconnect from the server
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
TCPIPClient.disconnect(handle)
isConnected()
Returns true if the client is connected
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
| Name | Type | Description |
|---|---|---|
isConnected |
BOOL |
True if the client is connected |
bConnected = TCPIPClient.isConnected(handle)
receive()
Receives data from the client with a specified timeout. If timeout is zero then it directly returns. The data could be framed if the "setFraming" function was called before. Incoming data between multiple receive calls is queued per message. There is a fix receive queue size of 10 packets per default and can be changed using the setReceiveQueueSize()-function. More data is discarded.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
timeout |
INT |
Timeout in ms to wait for received data. 0 is default and means directly return. |
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The data which was received |
local data = TCPIPClient.receive(handle, 1000)
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
setFraming()
Sets the framing which is to be used. If not set the default framing is no framing (raw byte/packet-wise connection). Framing could be also explicitly disabled by calling this function with 2 empty binary data for rx and tx. One framing part could be maximum size of 9 bytes. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
rxStart |
BINARY |
Start framing for receiving, could be empty string. Maximum size of 9. |
rxStop |
BINARY |
Stop framing for receiving. If empty then all raw data is received. Maximum size of 9. |
txStart |
BINARY |
Start framing for sending, could be empty string. Maximum size of 9. |
txStop |
BINARY |
Stop framing for sending, could be empty string. Maximum size of 9. |
TCPIPClient.setFraming(handle, "\02", "\03", "", "\013\010") -- STX...ETX for receiving and ...CR/LF for transmitting
setFramingBufferSize()
Sets the size of the internal framing parser buffer which is used if there is a rx or tx framing set using the setFraming function. If the rx or tx framing isn’t set, its buffer size has no effect. This size is the maximum size of a packet which can be parsed by the framing. The size is used for start and stop framing. Default is 10240 bytes.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
rxBufSize |
INT |
The new framing buffer size for framed receiving. |
txBufSize |
INT |
The new framing buffer size for framed transmitting. |
TCPIPClient.setFramingBufferSize(handle, 21000, 21000)
setIPAddress()
Sets the server ip address to connect to
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
ipAddress |
STRING |
The IP Address as string e.g. '192.168.0.10' |
TCPIPClient.setIPAddress(handle, "127.0.0.1")
setInterface()
Sets the interface to use for connecting.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
ifName |
ENUM EthernetInterfaces |
One of the available interfaces |
TCPIPClient.setInterface(handle, "ETH1")
setPort()
Sets the server port to connect to.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
port |
INT |
The server port between 1 and 65535 |
TCPIPClient.setPort(handle, 2120)
setReceiveQueueSize()
Sets the internal queue size for the receive()-function. Default is 10 packets and discarding the oldest item and warn if overrun occurs. Set to 0 to disable the queue and receiving from the receive()-function, which also increases performance if only receiving over OnReceive-event.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
queueSize |
INT |
The new receive queue size. |
bDiscardIfFull |
BOOL |
Set to true to discard the newest item which is currently added instead of discarding the oldest element. Default is false. |
warnOverruns |
BOOL |
Set to false to disable warning on overruns when using the receive()-function. Default is true. |
TCPIPClient.setReceiveQueueSize(handle, 50)
setStaticSourcePort()
Sets a static source port for the TCP/IP client. If this function is not used, the default behavior of the operating system is to select a free source port automatically. Do not use this function unless a custom protocol requires a static client port.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
port |
INT |
The client source port between 1 and 65535 |
TCPIPClient.setStaticSourcePort(handle, 2120)
setTransmitTimeout()
Sets the timeout for transmits in milliseconds.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
timeoutMs |
INT |
The timeout for transmits in milliseconds. |
TCPIPClient.setTransmitTimeout(handle, 5000)
transmit()
Transmits data to the server. If framing is set using the "setFraming" function, then the framing characters are automatically prefixed and suffixed to the transmitted data. Blocks until data has been transmitted. If transmit fails the return number of transmitted bytes is zero. If transmit fails the connection might be broken. The TCPIPClient would connect automatically again, but the user could also call disconnect()+connect() functions manually.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Client |
data |
BINARY |
The data which is to be transmitted |
| Name | Type | Description |
|---|---|---|
numberOfBytesTransmitted |
INT |
Number of bytes transmitted; 0 if transmit failed |
TCPIPClient.transmit(handle,"Hello Server")
Events
OnConnected
The on connected event which is thrown for every connect.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
This is a handle event and must be registered on the handle |
OnDisconnected
The on disconnected event which is thrown for every disconnect. The client automatically tries to connect again every 5 seconds, so the connect() function does not need to be called here.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
This is a handle event and must be registered on the handle |
OnReceive
The on receive event which is thrown for every new received data.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
This is a handle event and must be registered on the handle |
data |
BINARY |
The received data |
TCPIPServer
Provides possibility to open new TCP/IP server ports at the device. A TCP/IP Server must be created using the create-function and a port must be set using the setPort-function. After a call to the listen-function the server waits for new incoming connections. If new connections arrive, the "OnConnectionAccepted" event is thrown. The user has to call then the accept function to accept the connection. Every accepted connection has its one connection handle. On the connection handle the user could receive and transmit. Currently the number of maximum parallel connections is set to 10 per default and can be changed over the setMaxConnections-function. Further connections will be automatically rejected. If new data arrives on the connection, the "OnReceive" event of the TCP/IP server is thrown with the connection handle, which received data, and the received data as parameter. The connection can be closed by the server side by calling the "TCPIPServer.Connection.close" function. If the connection is closed by the peer or by the server side, the "OnConnectionClosed" event is thrown with the connection handle of the closed connection. The transmitted and received data is raw data. It could get automatically framed for transmitting and receiving can be automatically parsed if setting a framing with the "setFraming" function. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded.
Keywords
Ethernet
See also
Overview
Functions
create()
Creates a new TCP/IP server instance. Server stays active as long as this handle exists.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Server |
handle = TCPIPServer.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
listen()
Starts listening for new connections on the port. Remember to register for new connections before calling this function. If port or framing is changed, this function needs to be called to apply the settings and wait for connections on the changed port. The OnConnectionClosed function is called for existing accepted connections.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Server |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
Returns true if the listening on the port was successful |
TCPIPServer.listen(handle)
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
setFraming()
Sets the framing which is to be used. If not set the default framing is no framing (raw byte/packet-wise connection). Framing could be also explicitly disabled by calling this function with 2 empty binary data for rx and tx. One framing part could be maximum size of 9 bytes. If a framing is set, there is a fix buffer size of receiving and transmitting which is 10240 bytes per default and can be changed using the setFramingBufferSize()-function. Every data packet which is larger than this will be discarded. The listen function has to be called afterwards so that the setting gets active.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Server |
rxStart |
BINARY |
Start framing for receiving, could be empty string. Maximum size of 9. |
rxStop |
BINARY |
Stop framing for receiving. If empty then all raw data is received. Maximum size of 9. |
txStart |
BINARY |
Start framing for sending, could be empty string. Maximum size of 9. |
txStop |
BINARY |
Stop framing for sending, could be empty string. Maximum size of 9. |
TCPIPServer.setFraming(handle, "\02", "\03", "", "\013\010") -- STX...ETX for receiving and ...CR/LF for transmitting
setFramingBufferSize()
Sets the size of the internal framing parser buffer which is used if there is a rx or tx framing set using the setFraming function. If the rx or tx framing isn’t set, its buffer size has no effect. This size is the maximum size of a packet which can be parsed by the framing. The size is used for start and stop framing. Default is 10240 bytes. The listen function has to be called afterwards so that the setting gets active
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Server |
rxBufSize |
INT |
The new framing buffer size for framed receiving. |
txBufSize |
INT |
The new framing buffer size for framed transmitting. |
TCPIPServer.setFramingBufferSize(handle, 21000, 21000)
setInterface()
Sets the interface to use for listening. The listen function has to be called afterwards so that the setting gets active.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Server |
ifName |
ENUM EthernetInterfaces |
One of the available interfaces |
TCPIPServer.setInterface(handle, "ETH1")
setMaxConnections()
Sets the number of maximum parallel active connections. Further active connections are automatically discarded. The default is set to 10 connections. The listen function has to be called afterwards so that the setting gets active.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Server |
maxCons |
INT |
The max number of parallel active connections. |
TCPIPServer.setMaxConnections(handle, 5)
setPort()
Sets the server port which is to be used. The listen function has to be called afterwards so that the setting gets active.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Server |
port |
INT |
The server port between 1 and 65535 |
TCPIPServer.setPort(handle, 2120)
setTransmitTimeout()
Sets the timeout for transmits in milliseconds.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the TCP/IP Server |
timeoutMs |
INT |
The timeout for transmits in milliseconds. |
TCPIPServer.setTransmitTimeout(handle, 5000)
Events
OnConnectionAccepted
This event is thrown for every new connection which was accepted. The new connection is hold until the connected peer disconnects or the connection is rejected. To reject a connection, the function Connection.close can be called.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
This is a handle event and must be registered on the handle |
conHandle |
HANDLE |
The connection handle of the connection which is opened |
OnConnectionClosed
This event is thrown if a connection is closed by the connected peer. The connection handle is not usable anymore. The event is not thrown if the Connection.close function was called.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
This is a handle event and must be registered on the handle |
conHandle |
HANDLE |
The connection handle of the connection which is closed |
OnReceive
The on receive event which is thrown for every new received data.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
This is a handle event and must be registered on the handle |
conHandle |
HANDLE |
The connection handle of the connection which is closed |
data |
BINARY |
The received data. If a framing is set, only contains the content without the framing. |
TCPIPServer.Connection
Controls one connection of the TCP/IP Server. To close the connection just set the handle to nil.
Overview
Functions
close()
Closes the connection explicitly from the server side. The OnConnectionClosed event is not thrown.
| Name | Type | Description |
|---|---|---|
conHandle |
HANDLE |
The instance handle of the TCP/IP Server connection |
TCPIPServer.Connection.close(conHandle)
getPeerAddress()
Returns the IP address and port of the connected peer on this connection.
| Name | Type | Description |
|---|---|---|
conHandle |
HANDLE |
The instance handle of the TCP/IP Server connection |
| Name | Type | Description |
|---|---|---|
ipAddr |
STRING |
The IP address of the connected peer. Nil if not available. |
portNo |
INT |
The port number of the connected peer. Nil if not available. |
local ip, port = TCPIPServer.Connection.getPeerAddress(conHandle)
isConnected()
Returns true if the client connection is still connected
| Name | Type | Description |
|---|---|---|
conHandle |
HANDLE |
The instance handle of the TCP/IP Server connection |
| Name | Type | Description |
|---|---|---|
isConnected |
BOOL |
True if the client is connected |
local bConnected = TCPIPServer.Connection.isConnected(conHandle)
transmit()
Transmits data to the clients. If framing is set using the "setFraming" function, then the framing characters are automatically prefixed and suffixed to the transmitted data. Blocks until data has been transmitted.
| Name | Type | Description |
|---|---|---|
conHandle |
HANDLE |
The instance handle of the TCP/IP Server connection |
data |
BINARY |
The data which is to be transmitted |
| Name | Type | Description |
|---|---|---|
numberOfBytesTransmitted |
INT |
Number of bytes transmitted; 0 if transmit failed |
TCPIPServer.Connection.transmit(conHandle, "Hello Server")
Text
Iconic object used for displaying text in a View. Deprecated, please use plain strings and a TextDecoration object instead.
Overview
Functions
create()
Creates a new Text.
| Name | Type | Description |
|---|---|---|
text |
OBJECT Text |
A new text |
text = Text.create()
setPosition()
Set the text position.
| Name | Type | Description |
|---|---|---|
text |
OBJECT Text |
The instance to be used. |
posX |
INT |
X |
posY |
INT |
Y |
posZ |
INT |
Z (only useful if 3D viewer is used). |
Text.setPosition(text, 10, 10)
setSize()
Set the font size.
| Name | Type | Description |
|---|---|---|
text |
OBJECT Text |
The instance to be used. |
fonSize |
INT |
The font size. |
lineSpacing |
FLOAT |
The line spacing in % of the font-size. Default is 1.1 |
Text.setSize(text, 10)
setText()
Set the textual content.
| Name | Type | Description |
|---|---|---|
text |
OBJECT Text |
The instance to be used. |
textstring |
STRING |
The text |
Text.setText(text, "This is a text.")
Timer
Provides Timers which can expire and call automatically callbacks. Timers can run once or automatically periodic
Overview
Functions
create()
Sets up a timer with a specific expiration timer time after which the specified callback function is called automatically. Timer needs to be started explicitly.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Unique handle for the timer |
handle = Timer.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
setExpirationTime()
Sets the expiration time of the timer in milliseconds. Default is 5000. New time is used next time calling start().
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
timeMS |
INT |
The expire time of the timer in milliseconds. Must be greater than 0. |
Timer.setExpirationTime(handle, 5000)
setPeriodic()
Sets the timer to periodic. Default is not periodic.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
isPeriodic |
BOOL |
True if timer occurs periodically until it is stopped or destroyed. Default is false. |
Timer.setPeriodic(handle, true)
start()
Starts the timer
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
Timer.start(handle)
stop()
Stops the timer
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to use |
Timer.stop(handle)
Events
OnExpired
This event is thrown every time the timer expires
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
This is a handle event and must be registered on the handle |
Timer.register(handle, "OnExpired", "handleExpired")
Transform
Object representing a linear transform in 2D or 3D space.
Overview
clone(), compose(), createFromMatrix2D(), createFromMatrix3D(), createHomography2D(), createHomography2DFromPoints(), createHomography3D(), createIdentity2D(), createIdentity3D(), createReflection2D(), createReflection3D(), createRigid2D(), createRigidAxisAngle3D(), createRigidEuler3D(), createScaling2D(), createScaling3D(), createSimilarity2D(), createTranslation2D(), createTranslation3D(), decomposeRigid2D(), decomposeRigidEuler3D(), decomposeSimilarity2D(), decomposeSimilarity3D(), decomposeTranslation2D(), decomposeTranslation3D(), getMatrix(), getType(), invert(), rotate2D(), rotateX(), rotateY(), rotateZ(), scale2D(), scale3D(), to3D(), toString(), toType(), translate2D(), translate3D()
Functions
clone()
Duplicates the transform.
| Name | Type | Description |
|---|---|---|
transform |
CONST_OBJECT Transform |
The instance to use |
| Name | Type | Description |
|---|---|---|
clone |
OBJECT Transform |
The duplicated transform |
local clonedTransform = Transform.clone(transform)
compose()
Composes two transforms of the same dimensionality.
Transform.rotate2D, Transform.rotateX, Transform.rotateY, Transform.rotateZ, Transform.scale3D, Transform.translate2D, Transform.translate3D, Transform.scale2D
| Name | Type | Description |
|---|---|---|
transformA |
CONST_OBJECT Transform |
The instance to use |
transformB |
CONST_OBJECT Transform |
The instance to use |
| Name | Type | Description |
|---|---|---|
composedTransform |
OBJECT Transform |
The composed transformation matrix. |
local composedTransform = Transform.compose(transformA, transformB)
createFromMatrix2D()
Creates a 2D transform directly from a 3x3 matrix representation.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
A 3x3 matrix with the transform. |
desiredType |
ENUM TransformType |
The desired transform type. If the numerical properties of the matrix does not fit the desired type, nil is returned. Optional, if not specified, the transform type is found by a numerical evaluation of the matrix. |
| Name | Type | Description |
|---|---|---|
transform |
OBJECT Transform |
The new 2D transform. |
local transform = Transform.createFromMatrix2D(matrix, desiredType)
createFromMatrix3D()
Creates a 3D transform directly from a 4x4 matrix representation.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
A 4x4 matrix with the transform. |
desiredType |
ENUM TransformType |
The desired transform type. If the numerical properties of the matrix does not fit the desired type, nil is returned. Optional, if not specified, the transform type is found by a numerical evaluation of the matrix. |
| Name | Type | Description |
|---|---|---|
transform |
OBJECT Transform |
The new 3D transform. |
local transform = Transform.createFromMatrix3D(matrix, desiredType)
createHomography2D()
Creates a 2D homography/projective transform.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
A 3x3 matrix with the full homography transform. |
| Name | Type | Description |
|---|---|---|
homographyTransform |
OBJECT Transform |
The new 2D homography transform |
local homographyTransform = Transform.createHomography2D(matrix)
createHomography2DFromPoints()
Creates a homography/projective transform from N corresponding point pairs, source and destination points need to be of equal length. If more than 4 points are given an RANSAC estimation of the homography is performed. If either margin or iterations is set to zero all points provided will be used.
| Name | Type | Description |
|---|---|---|
srcPoints |
CONST_OBJECT Point |
N source points. |
dstPoints |
CONST_OBJECT Point |
N destination points. |
margin |
FLOAT |
Margin expressed in world-units. Points which after transformation is within the margin is considered as inliers. Default value is 1.0. If the certainty of the points is high the margin can be lowered to reject more outliers. |
iterations |
INT |
Number of iterations in the RANSAC loop in the homography estimation. Default value is 100. If set to 0 a least-squares estimation is performed. |
| Name | Type | Description |
|---|---|---|
homographyTransform |
OBJECT Transform |
Homography transform. |
local homographyTransform = Transform.createHomography2DFromPoints(srcPoints, dstPoints, margin, iterations)
createHomography3D()
Creates a 3D homography/projective transform.
| Name | Type | Description |
|---|---|---|
matrix |
CONST_OBJECT Matrix |
A 4x4 matrix with the full homography transform. |
| Name | Type | Description |
|---|---|---|
homographyTransform |
OBJECT Transform |
The new 3D homography transform |
local homographyTransform = Transform.createHomography3D(matrix)
createIdentity2D()
Creates a new 2D transform with no rotation, scale or translation.
| Name | Type | Description |
|---|---|---|
transform |
OBJECT Transform |
The new 2D identity transform |
local transform = Transform.createIdentity2D()
createIdentity3D()
Creates a new 3D transform with no rotation, scale or translation.
| Name | Type | Description |
|---|---|---|
transform |
OBJECT Transform |
The new 3D identity transform |
local transform = Transform.createIdentity3D()
createReflection2D()
Creates a 2D rigid transform that is a reflection in the given 2D line.
mirror
| Name | Type | Description |
|---|---|---|
line |
CONST_OBJECT Shape |
The reflection 2D line. |
| Name | Type | Description |
|---|---|---|
reflection |
OBJECT Transform |
The new 2D reflection transform which is of RIGID type. |
local reflection = Transform.createReflection2D(line)
createReflection3D()
Creates a 3D rigid transform that is a reflection in the given 3D plane.
| Name | Type | Description |
|---|---|---|
plane |
CONST_OBJECT Shape3D |
The reflection 3D plane. |
| Name | Type | Description |
|---|---|---|
reflection |
OBJECT Transform |
The new 3D reflection transform which is of RIGID type. |
local reflection = Transform.createReflection3D(plane)
createRigid2D()
Creates a 2D rigid transform with only rotation and translation.
Transform.createReflection2D, Transform.rotate2D, Transform.rotateY, Transform.translate2D, Transform.rotateX
| Name | Type | Description |
|---|---|---|
rotation |
FLOAT |
Counter clockwise rotation (in radians) |
xTrans |
FLOAT |
Translation in the x direction |
yTrans |
FLOAT |
Translation in the y direction |
origin |
CONST_OBJECT Point |
Optional origin of rotation if other than (0,0) |
| Name | Type | Description |
|---|---|---|
rigidTransform |
OBJECT Transform |
The new 2D rigid transform |
local rigidTransform = Transform.createRigid2D(math.pi/2, xTrans, yTrans, origin)
createRigidAxisAngle3D()
Creates a 3D rigid transform by defining an axis, a rotation around the axis and a translation.
Transform.createReflection3D, Transform.rotateX, Transform.rotateY, Transform.scale3D, transform.RotateZ, Transform.decomposeRigidEuler3D
| Name | Type | Description |
|---|---|---|
axis |
FLOAT |
The rotation axis to rotate about. |
rotation |
FLOAT |
Clockwise rotation when looking along the axis (in radians) |
xTrans |
FLOAT |
Translation in the x direction |
yTrans |
FLOAT |
Translation in the y direction |
zTrans |
FLOAT |
Translation in the z direction |
origin |
CONST_OBJECT Point |
Optional origin of rotation if other than (0,0,0) |
| Name | Type | Description |
|---|---|---|
rigidTransform |
OBJECT Transform |
The new 3D rigid transform |
local rigidTransform = Transform.createRigidAxisAngle3D({xAxis, yAxis, zAxis}, rotation, xTrans, yTrans, zTrans, origin)
createRigidEuler3D()
Creates a 3D rigid transform using Euler angles and translation. Rotations are parameterized and applied in the order specified by the rotation order. E.g. using order "XYZ", the object is first rotated alpha radians around the world x-axis, then beta radians around the world y-axis, and finally gamma radians around the world z-axis. All rotations are according to the right hand rule, positive is clockwise when looking along the direction of the rotation axis.
[API:Crown:], Transform.createReflection3D, Transform.rotateX, Transform.rotateY, Transform.scale3D, Transform.translate3D, transform.RotateZ, Transform.decomposeRigidEuler3D
| Name | Type | Description |
|---|---|---|
rotationOrder |
ENUM RotationOrder |
Order in which to apply rotations and order of rotation parameters. |
alpha |
FLOAT |
Rotation around the first axis (in radians). |
beta |
FLOAT |
Rotation arond the second axis (in radians). |
gamma |
FLOAT |
Rotation around the third axis (in radians). |
xTrans |
FLOAT |
Translation in the x direction. |
yTrans |
FLOAT |
Translation in the y direction. |
zTrans |
FLOAT |
Translation in the z direction. |
origin |
CONST_OBJECT Point |
Optional origin of rotation if other than (0,0,0). |
| Name | Type | Description |
|---|---|---|
rigidTransform |
OBJECT Transform |
The new 3D rigid transform |
local rigidTransform = Transform.createRigidEuler3D(rotationOrder, alpha, beta, gamma, xTrans, yTrans, zTrans, origin)
createScaling2D()
Creates a 2D scaling transform which scales in the x- and y-dimensions.
| Name | Type | Description |
|---|---|---|
xScale |
FLOAT |
Scaling in the x direction |
yScale |
FLOAT |
Optional scaling in the y direction. If omitted the same scaling will be used in both x and y direction. |
origin |
CONST_OBJECT Point |
Optional origin of scaling if other than (0,0) |
| Name | Type | Description |
|---|---|---|
transform |
OBJECT Transform |
The new 2D scaling transform which is of type SIMILARITY |
local transform = Transform.createScaling2D(xScale, yScale, origin)
createScaling3D()
Creates a 3D scaling transform which scales in the x-, y-, and z-dimensions.
| Name | Type | Description |
|---|---|---|
xScale |
FLOAT |
Scaling in the x direction |
yScale |
FLOAT |
Optional scaling in the y direction. If omitted the scaling for the x direction will also be used in the y direction. |
zScale |
FLOAT |
Optional scaling in the z direction. If omitted the scaling for the x direction will also be used in the z direction. |
origin |
CONST_OBJECT Point |
Optional origin of scaling if other than (0,0) |
| Name | Type | Description |
|---|---|---|
transform |
OBJECT Transform |
The new 3D scaling transform which is of type SIMILARITY |
local transform = Transform.createScaling3D(xScale, yScale, zScale, origin)
createSimilarity2D()
Creates a 2D similarity transform with rotation, scale and translation.
| Name | Type | Description |
|---|---|---|
rotation |
FLOAT |
Counter clockwise rotation (in radians) |
scale |
FLOAT |
Scale factor |
xTrans |
FLOAT |
Translation in the x direction |
yTrans |
FLOAT |
Translation in the y direction |
origin |
CONST_OBJECT Point |
Optional origin of rotation if other than (0,0) |
| Name | Type | Description |
|---|---|---|
similarityTransform |
OBJECT Transform |
The new 2D similarity transform |
local similarityTransform = Transform.createSimilarity2D(math.pi/2, scale, xTrans, yTrans, origin)
createTranslation2D()
Creates a 2D translational transform.
| Name | Type | Description |
|---|---|---|
xTrans |
FLOAT |
Translation in the x direction |
yTrans |
FLOAT |
Translation in the y direction |
| Name | Type | Description |
|---|---|---|
transform |
OBJECT Transform |
The new 2D translational transform |
local transform = Transform.createTranslation2D(xTrans, yTrans)
createTranslation3D()
Creates a 3D translational transform.
| Name | Type | Description |
|---|---|---|
xTrans |
FLOAT |
Translation in the x direction |
yTrans |
FLOAT |
Translation in the y direction |
zTrans |
FLOAT |
Translation in the z direction |
| Name | Type | Description |
|---|---|---|
transform |
OBJECT Transform |
The new 3D translational transform |
local transform = Transform.createTranslation3D(xTrans, yTrans, zTrans)
decomposeRigid2D()
Decomposes a 2D rigid transform into rotation and translation components. The transform must not contain a reflection.
| Name | Type | Description |
|---|---|---|
rigidTransform |
CONST_OBJECT Transform |
The 2D rigid transform. |
| Name | Type | Description |
|---|---|---|
rotation |
FLOAT |
Counter clockwise rotation (in radians). |
xTrans |
FLOAT |
Translation in the x direction. |
yTrans |
FLOAT |
Translation in the y direction. |
local rotation, xTrans, yTrans = Transform.decomposeRigid2D(rigidTransform)
decomposeRigidEuler3D()
Decomposes a 3D rigid transform into Euler angles and translation. Rotations are parameterized and applied in the order specified by the rotation order. E.g. to recreate a transformation decomposed using "ZYX" rotation order, first rotate alpha around the world z-axis, then beta around the world y-axis and finally gamma around the world x-axis. All rotations are according to the right hand rule, positive is clockwise when looking along the direction of the rotation axis. The transform must not contain a reflection.
| Name | Type | Description |
|---|---|---|
rigidTransform |
CONST_OBJECT Transform |
The 3D rigid transform. |
rotationOrder |
ENUM RotationOrder |
Order in which to apply rotations and order of the returned rotation parameters. |
| Name | Type | Description |
|---|---|---|
alpha |
FLOAT |
Rotation around the first axis (in radians). |
beta |
FLOAT |
Rotation arond the second axis (in radians). |
gamma |
FLOAT |
Rotation around the third axis (in radians). |
xTrans |
FLOAT |
Translation in the x direction. |
yTrans |
FLOAT |
Translation in the y direction. |
zTrans |
FLOAT |
Translation in the z direction. |
local alpha, beta, gamma, xTrans, yTrans, zTrans = Transform.decomposeRigidEuler3D(rigidTransform, rotationOrder)
decomposeSimilarity2D()
Decomposes a similarity transform into a rigid transform and a scale factor. The similarity transform can be reconstructed by first scaling and then applying the rigid transformation.
| Name | Type | Description |
|---|---|---|
similarityTransform |
CONST_OBJECT Transform |
The 2D similarity transform. |
| Name | Type | Description |
|---|---|---|
scale |
FLOAT |
Scale factor. |
rigidTransform |
OBJECT Transform |
The rigid part of the transform. |
local scale, rigidTransform = Transform.decomposeSimilarity2D(similarityTransform)
decomposeSimilarity3D()
Decomposes a similarity transform into a rigid transform and a scale factor. The similarity transform can be reconstructed by first scaling and then applying the rigid transformation.
| Name | Type | Description |
|---|---|---|
similarityTransform |
CONST_OBJECT Transform |
The 3D similarity transform. |
| Name | Type | Description |
|---|---|---|
scale |
FLOAT |
Scale factor. |
rigidTransform |
OBJECT Transform |
The rigid part of the transform. |
local scale, rigidTransform = Transform.decomposeSimilarity3D(similarityTransform)
decomposeTranslation2D()
Decomposes a 2D translation transform into translation components.
| Name | Type | Description |
|---|---|---|
translationTransform |
CONST_OBJECT Transform |
The 2D translation transform. |
| Name | Type | Description |
|---|---|---|
xTrans |
FLOAT |
Translation in the x direction. |
yTrans |
FLOAT |
Translation in the y direction. |
local xTrans, yTrans = Transform.decomposeTranslation2D(translationTransform)
decomposeTranslation3D()
Decomposes a 3D translation transform into translation components.
| Name | Type | Description |
|---|---|---|
translationTransform |
CONST_OBJECT Transform |
The 3D translation transform. |
| Name | Type | Description |
|---|---|---|
xTrans |
FLOAT |
Translation in the x direction. |
yTrans |
FLOAT |
Translation in the y direction. |
zTrans |
FLOAT |
Translation in the z direction. |
local xTrans, yTrans, zTrans = Transform.decomposeTranslation3D(translationTransform)
getMatrix()
Returns the transform matrix.
| Name | Type | Description |
|---|---|---|
transform |
CONST_OBJECT Transform |
The instance to use |
| Name | Type | Description |
|---|---|---|
matrix |
OBJECT Matrix |
The full 3x3 or 4x4 matrix of this transform. |
local matrix = Transform.getMatrix(transform)
getType()
Returns the transform type
| Name | Type | Description |
|---|---|---|
transform |
CONST_OBJECT Transform |
The transform to check |
| Name | Type | Description |
|---|---|---|
result |
ENUM TransformType |
The transform type |
if (Transform.getType(transform)=="IDENTITY") then
doSomething()
end
invert()
Returns the inverse transform.
| Name | Type | Description |
|---|---|---|
transform |
CONST_OBJECT Transform |
The instance to use |
| Name | Type | Description |
|---|---|---|
inversedTransform |
OBJECT Transform |
The inverse transformation matrix. |
local inversedTransform = Transform.invert(transform)
rotate2D()
Returns a 2D transform with a counter clockwise rotation appended to the input transform. The rotation center is optional. If not provided, the world origin is used.
| Name | Type | Description |
|---|---|---|
inputTransform |
CONST_OBJECT Transform |
Input 2D transform. |
rotationAngle |
FLOAT |
The rotation angle in radians. |
rotationCenter |
CONST_OBJECT Point |
The rotation center. Default is the origin. |
| Name | Type | Description |
|---|---|---|
outputTransform |
OBJECT Transform |
The transform with appended rotation. |
outputTransform = Transform.rotate2D(inputTransform, rotationAngle, rotationCenter)
rotateX()
Returns a 3D transform with a rotation around an axis parallel to the world x-axis appended to the input transform. The rotation center is optional. If not provided, the world origin is used. Positive rotation is according to the right hand rule, clockwise when looking along the direction of the rotation axis.
| Name | Type | Description |
|---|---|---|
inputTransform |
CONST_OBJECT Transform |
Input 3D transform. |
rotationAngle |
FLOAT |
The rotation angle in radians. |
rotationCenter |
CONST_OBJECT Point |
The rotation center. Default is the origin. |
| Name | Type | Description |
|---|---|---|
outputTransform |
OBJECT Transform |
The transform with appended rotation. |
outputTransform = Transform.rotateX(inputTransform, rotationAngle, rotationCenter)
rotateY()
Returns a 3D transform with a rotation around an axis parallel to the world y-axis appended to the input transform. The rotation center is optional. If not provided, the world origin is used. Positive rotation is according to the right hand rule, clockwise when looking along the direction of the rotation axis.
| Name | Type | Description |
|---|---|---|
inputTransform |
CONST_OBJECT Transform |
Input 3D transform. |
rotationAngle |
FLOAT |
The rotation angle in radians. |
rotationCenter |
CONST_OBJECT Point |
The rotation center. Default is the origin. |
| Name | Type | Description |
|---|---|---|
outputTransform |
OBJECT Transform |
The transform with appended rotation. |
outputTransform = Transform.rotateY(inputTransform, rotationAngle, rotationCenter)
rotateZ()
Returns a 3D transform with a rotation around an axis parallel to the world z-axis appended to the input transform. The rotation center is optional. If not provided, the world origin is used. Positive rotation is according to the right hand rule, clockwise when looking along the direction of the rotation axis.
| Name | Type | Description |
|---|---|---|
inputTransform |
CONST_OBJECT Transform |
Input 3D transform. |
rotationAngle |
FLOAT |
The rotation angle in radians. |
rotationCenter |
CONST_OBJECT Point |
The rotation center. Default is the origin. |
| Name | Type | Description |
|---|---|---|
outputTransform |
OBJECT Transform |
The transform with appended rotation. |
outputTransform = Transform.rotateZ(inputTransform, rotationAngle, rotationCenter)
scale2D()
Returns a 2D transform with a scaling appended to the input transform.
| Name | Type | Description |
|---|---|---|
inputTransform |
CONST_OBJECT Transform |
Input 2D transform. |
scaleFactor |
FLOAT |
The scaling factor to apply. |
scaleCenter |
CONST_OBJECT Point |
The scaling center, remains fixed during scaling. Default is the origin. |
| Name | Type | Description |
|---|---|---|
outputTransform |
OBJECT Transform |
The transform with appended scaling. |
outputTransform = Transform.scale2D(inputTransform, scaleFactor)
scale3D()
Returns a 3D transform with a scaling appended to the input transform.
| Name | Type | Description |
|---|---|---|
inputTransform |
CONST_OBJECT Transform |
Input 3D transform. |
scaleFactor |
FLOAT |
The scaling factor to apply. |
scaleCenter |
CONST_OBJECT Point |
The scaling center, remains fixed during scaling. Default is the origin. |
| Name | Type | Description |
|---|---|---|
outputTransform |
OBJECT Transform |
The transform with appended scaling. |
outputTransform = Transform.scale3D(inputTransform, scaleFactor)
to3D()
Converts a 2D transform to a 3D transform. The created 3D transform applies the 2D transform to the x,y-coordinates and leaves the z-coordinates unchanged. This holds up to affine transformations. For homographies, the final scaling of the points is applied also to the z-coordinate.
| Name | Type | Description |
|---|---|---|
transform2d |
CONST_OBJECT Transform |
The 2D source transform. |
| Name | Type | Description |
|---|---|---|
transform3d |
OBJECT Transform |
The corresponding 3D transform. Nil is returned if input is invalid. |
local transform3d Transform.to3D(transform2d)
toString()
Get a string representation of the transform. The matrix representing the transform is written row-wise.
| Name | Type | Description |
|---|---|---|
transform |
CONST_OBJECT Transform |
Input transform |
| Name | Type | Description |
|---|---|---|
str |
STRING |
String representation of the transform |
print("The transform is: " .. transform:toString())
toType()
Returns a copy of the transformation marked as desired type. If the desired type is not general enough to support the actual transformation, nil is returned. The transform itself is not changed. Converting to a more general type always succeeds.
| Name | Type | Description |
|---|---|---|
transform |
CONST_OBJECT Transform |
The source transform. |
desiredType |
ENUM TransformType |
The desired transform type, e.g., RIGID, SIMILARITY, AFFINE, TRANSLATION. |
| Name | Type | Description |
|---|---|---|
convertedTransform |
OBJECT Transform |
The transform of the desired type, or nil if the desired type was not compatible with the actual transform. |
local convertedTransform Transform.toType(transform, "RIGID")
translate2D()
Returns a 2D transform with a translation in world coordinates appended to the input transform.
| Name | Type | Description |
|---|---|---|
inputTransform |
CONST_OBJECT Transform |
Input 2D transform. |
xTrans |
FLOAT |
The translation along the x-axis. |
yTrans |
FLOAT |
The translation along the y-axis. |
| Name | Type | Description |
|---|---|---|
outputTransform |
OBJECT Transform |
The transform with appended translation. |
outputTransform = Transform.translate2D(inputTransform, xTrans, yTrans)
translate3D()
Returns a 3D transform with a translation in world coordinates appended to the input transform.
| Name | Type | Description |
|---|---|---|
inputTransform |
CONST_OBJECT Transform |
Input 3D transform. |
xTrans |
FLOAT |
The translation along the x-axis. |
yTrans |
FLOAT |
The translation along the y-axis. |
zTrans |
FLOAT |
The translation along the z-axis. |
| Name | Type | Description |
|---|---|---|
outputTransform |
OBJECT Transform |
The transform with appended translation. |
outputTransform = Transform.translate3D(inputTransform, xTrans, yTrans, zTrans)
TriSpector
TriSpectorP specific functionality.
Functions
getLaserEnabled()
Returns true if the laser is on.
| Name | Type | Description |
|---|---|---|
enabled |
BOOL |
true if the laser is on. |
enabled = TriSpector.getLaserEnabled()
readTriSpector1000Heightmap()
Read the TriSpector1000 image format (png).
| Name | Type | Description |
|---|---|---|
path |
STRING |
Path to input file |
| Name | Type | Description |
|---|---|---|
heightImage |
OBJECT Image |
Height map |
reflectanceImage |
OBJECT Image |
Reflectance image |
heightImage, reflectanceImage = TriSpector.readTriSpector1000Heightmap("resources/image.png")
setLaserEnabled()
Turn laser on or off.
| Name | Type | Description |
|---|---|---|
enable |
BOOL |
true to turn laser on, false to turn it off. |
TriSpector.setLaserEnabled(true)
UDPSocket
Provides functionality for sending/receiving UDP packets. First a new UDPSocket needs to be created using the create function. Afterwards it could be set to a specified interface using setInterface()-function. Then a call to the bind-function binds the udp socket to a port and transmit calls and OnReceive events are possible. If bind()-function is not called, the socket is bind implicitly to the first transmit target. Data could be transmitted to the server using the "transmit" function. Data could be received by a register to the "OnReceive" event or by calling the blocking receive()-function.
Overview
Functions
bind()
Binds the socket to a specific local port.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the UDP socket |
port |
INT |
The port to bind to |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if socket was bound successfully, false if an error occurred. |
success = UDPSocket.bind(handle, 10000)
create()
Creates a UDP socket instance.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the UDP socket |
handle = UDPSocket.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
receive()
Receives one UDP packet with a specified timeout. The socket must be bound first either explicitly by calling bind or implicitly by a preceding transmit. If timeout is zero then it directly returns without any return values. Incoming data between multiple receive calls is queued per message. There is a fix receive queue size of 10 packets per default and can be changed using the setReceiveQueueSize()-function. More data is discarded.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the UDP socket |
timeout |
INT |
Timeout in ms to wait for received data. 0 is default and means directly return. |
| Name | Type | Description |
|---|---|---|
data |
BINARY |
The received data |
ipAddress |
STRING |
The peer address the data was received from |
port |
INT |
The peer port the data was received from |
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
setInterface()
Sets the interface to bind the socket to.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the UDP socket |
ifName |
ENUM EthernetInterfaces |
One of the available interfaces |
UDPSocket.setInterface(handle, "ETH1")
setReceiveQueueSize()
Sets the internal queue size for the receive()-function. Default is 10 packets and discarding the oldest item and warn if overrun occurs. Set to 0 to disable the queue and receiving from the receive()-function, which also increases performance if only receiving over OnReceive-event.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the UDP socket |
queueSize |
INT |
The new receive queue size. |
bDiscardIfFull |
BOOL |
Set to true to discard the newest item which is currently added instead of discarding the oldest element. Default is false. |
warnOverruns |
BOOL |
Set to false to disable warning on overruns when using the receive()-function. Default is true. |
UDPSocket.setReceiveQueueSize(handle, 50)
transmit()
Transmit a UDP packet to the specified peer. This will trigger an implicit bind if the socket has not been bound yet.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the UDP socket |
ipAddress |
STRING |
The ip address to transmit to |
port |
INT |
The port to transmit to |
data |
BINARY |
The data which to be transmitted |
| Name | Type | Description |
|---|---|---|
numberOfBytesTransmitted |
INT |
Number of bytes transmitted; 0 if transmit failed |
transmitted = UDPSocket.transmit(handle, "192.168.0.1", 10000, "Hello world")
Events
OnReceive
The event which is triggered when data is received on the socket. The socket must be bound first either explicitly by calling bind or implicitly by a preceding transmit. For each packet receive there is one event thrown.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle of the UDP socket |
data |
BINARY |
The received data packet |
ipAddress |
STRING |
The peer address the data was received from |
port |
INT |
The peer port the data was received from |
View
Provides view function for iconics like Text, Scan, Image and PointCloud.
Overview
add(), addGraph(), addHeightmap(), addImage(), addMesh(), addPixelRegion(), addPoint(), addPointCloud(), addProfile(), addShape(), addText(), clear(), countConnections(), create(), deregister(), installEditor(), present(), rasterize(), register(), remove(), setDefaultDecoration(), setFillColor(), setID(), setLineColor(), setLineWidth(), uninstallEditor(), updateCamera(), updateDecoration(), updateTransform(), view()
Functions
add()
Adds the iconics, with an optional decoration, to be shown in viewers when View.present is called. If the decoration is omitted a default decoration is used. Iconics are stored by reference, if they are modified between View.add and View.present, only their latest state will be presented. This function is deprecated. Use View.addXYZ instead. Reasons for deprecation: type-safety, missing parent-id leads to usage of wrong coordinate-systems.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
iconics |
CONST_AUTO |
The iconic or list of iconics to be viewed. |
decoration |
CONST_OBJECT [API:DataFormat:] |
Optional decoration for the iconics. |
View.add(handle, iconics, decoration)
addGraph()
Adds a graph to be shown in viewers when View.present is called. The graph type, e.g., xy-plot or histogram, is set by the GraphDecoration object. If the parentId refers to an Image, the graph will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
values |
FLOAT |
A vector of float values to be plotted on the y-axis of the graph. |
coordinates |
FLOAT |
Optional vector of float values for the x-axis, e.g., time, position etc. The default value is an empty vector, in which case the integer indexes of the value vector are used. |
decoration |
CONST_OBJECT View.GraphDecoration |
Optional decoration for the graph. |
iconicId |
STRING |
Optional iconic id. |
parentId |
STRING |
Optional parent id. |
| Name | Type | Description |
|---|---|---|
iconicId |
STRING |
Iconic id. An id is generated if not provided. |
iconicId = View.addGraph(handle, values, coordinates, decoration, iconicId)
addHeightmap()
Adds an Image that is shown as a heightmap in viewers when View.present is called. If a list of images is used, the first image will be presented as the heightmap. Consecutive images are used as selectable view-components (textures) for the heightmap using the labels from the labels list argument.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
images |
CONST_OBJECT Image |
The heightmap to be viewed. Additional images will be used as selectable view components. |
decorations |
CONST_OBJECT View.ImageDecoration |
Optional decorations for the image(s). |
labels |
STRING |
Optional labels for the additional images |
iconicId |
STRING |
Optional iconic id. |
parentId |
STRING |
Optional parent id. The same parent id is used for all added images. |
| Name | Type | Description |
|---|---|---|
iconicId |
STRING |
Iconic id. An id is generated if not provided. |
iconicId = View.addHeightmap(handle, {heightmap, reflectance}, {reflectanceDecoration}, {"Reflectance"}, "heightmap1")
addImage()
Adds one or more Image to be shown in viewers when View.present is called.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
image |
CONST_OBJECT Image |
The image(s) to be viewed. |
decoration |
CONST_OBJECT View.ImageDecoration |
Optional decoration for the image(s). |
iconicId |
STRING |
Optional iconic id(s). One iconic id per image must be supplied if this parameter is used. |
parentId |
STRING |
Optional parent id. The same parent id is used for all added images. |
| Name | Type | Description |
|---|---|---|
iconicId |
STRING |
A (vector of) iconic id(s). Id(s) are generated if not provided. |
iconicId = View.addImage(handle, image, imageDecoration, "image1")
addMesh()
Adds one or more Meshes to be shown in viewers when View.present is called.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
mesh |
OBJECT Mesh |
The mesh(es) to be viewed. |
decoration |
CONST_OBJECT View.MeshDecoration |
Optional decoration for the mesh(es). |
iconicId |
STRING |
Optional iconic id(s). One iconic id per mesh must be supplied if this parameter is used. |
parentId |
STRING |
Optional parent id. The same parent id is used for all added meshes. |
| Name | Type | Description |
|---|---|---|
iconicId |
STRING |
A (vector of) iconic id(s). Id(s) are generated if not provided. |
iconicId = View.addMesh(handle, mesh, decoration, "mesh1")
addPixelRegion()
Adds one or more Image.PixelRegion to be shown as an overlay for an iconic or separately when View.present is called. If a parentId is given, the PixelRegion is displayed as a clipped overlay for the given parent, otherwise it is drawn separately in world-coordinates.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
pixelRegion |
CONST_OBJECT Image.PixelRegion |
The pixel region(s) to be viewed. |
decoration |
CONST_OBJECT View.PixelRegionDecoration |
Optional decoration for the pixel region(s). The same decoration is used for all added pixel regions. |
iconicId |
STRING |
Optional iconic id(s). One iconic id per pixel region must be supplied if this parameter is used. |
parentId |
STRING |
Optional parent id. The same parent id is used for all added pixel regions. |
| Name | Type | Description |
|---|---|---|
iconicId |
STRING |
A (vector of) iconic id(s). Id(s) are generated if not provided. |
iconicId = View.addPixelRegion(handle, pixelRegion, pixelRegionDecoration, "pixelRegion1", "image1")
addPoint()
Adds one or more Point objects to be shown in viewers when View.present is called. If the parentId refers to an Image, the point will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
point |
CONST_OBJECT [API:DataFormat:] |
The point(s) which is to be viewed. |
decoration |
CONST_OBJECT View.ShapeDecoration |
Optional decoration for the point. The same decoration is used for all added points. N.B: A ShapeDecoration shall be used, there is no dedicated decoration only for Points. |
iconicId |
STRING |
Optional iconic id(s). One iconic id per point must be supplied if this parameter is used. |
parentId |
STRING |
Optional parent id. The same parent id is used for all added points. |
| Name | Type | Description |
|---|---|---|
iconicId |
STRING |
A (vector of) iconic id(s). Id(s) are generated if not provided. |
iconicId = View.addPoint(handle, point, shapeDecoration, "point1", "image1")
addPointCloud()
Adds one or more PointClouds to be shown in viewers when View.present is called.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
pointCloud |
CONST_OBJECT PointCloud |
The point cloud(s) to be viewed. |
decoration |
CONST_OBJECT View.PointCloudDecoration |
Optional decoration for the point cloud(s). |
iconicId |
STRING |
Optional iconic id(s). One iconic id per point cloud must be supplied if this parameter is used. |
parentId |
STRING |
Optional parent id. The same parent id is used for all added pointClouds. |
| Name | Type | Description |
|---|---|---|
iconicId |
STRING |
A (vector of) iconic id(s). Id(s) are generated if not provided. |
iconicId = View.addPointCloud(handle, pointCloud, pointCloudDecoration, "pointcloud1")
addProfile()
Adds one or more profiles to be shown in viewers when View.present is called. The visualization properties are specified using a GraphDecoration object. If the parentId refers to an Image, the profile will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
profile |
OBJECT Profile |
The profile(s) to be viewed. |
decoration |
CONST_OBJECT View.GraphDecoration |
Optional decoration for the profile. |
iconicId |
STRING |
Optional iconic id(s). One iconic id per profile must be supplied if this parameter is used. |
parentId |
STRING |
Optional parent id. The same parent id is used for all added profiles. |
| Name | Type | Description |
|---|---|---|
iconicId |
STRING |
A (vector of) iconic id(s). Id(s) are generated if not provided. |
iconicId = View.addProfile(handle, profile, decoration, iconicId)
addShape()
Adds either one or more Shape/Shape3D objects to be shown in viewers when View.present is called. If the parentId refers to an Image, the shape will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
shape |
CONST_OBJECT [API:DataFormat:] |
The shape(s)/point(s) which is to be viewed. |
decoration |
CONST_OBJECT View.ShapeDecoration |
Optional decoration for the shape. The same decoration is used for all added shapes. |
iconicId |
STRING |
Optional iconic id(s). One iconic id per shape must be supplied if this parameter is used. |
parentId |
STRING |
Optional parent id. The same parent id is used for all added shapes. |
| Name | Type | Description |
|---|---|---|
iconicId |
STRING |
A (vector of) iconic id(s). Id(s) are generated if not provided. |
iconicId = View.addShape(handle, shape, shapeDecoration, "shape1", "image1")
addText()
Adds a string to be drawn when View.present is called. If the parentId refers to an Image, the text will be drawn relative to its coordinate system. If no parent is given, it is drawn relative to the world coordinate system.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
text |
STRING |
The text which is to be viewed. |
decoration |
CONST_OBJECT View.TextDecoration |
Optional decoration for the text. |
iconicId |
STRING |
Optional iconic id. |
parentId |
STRING |
Optional parent id. |
| Name | Type | Description |
|---|---|---|
iconicId |
STRING |
Iconic id. An id is generated if not provided. |
iconicId = View.addText(handle, "Hello world", textDecoration, "text1", "image1")
clear()
Removes all previously added iconics from viewers when View.present is called.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
View.clear(handle)
countConnections()
Returns the number of connected viewers at this viewer’s identifier. If no identifier is set, it counts all connected viewers on all identifiers.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
| Name | Type | Description |
|---|---|---|
connectedCount |
INT |
The number of connected viewers or 0 if none is connected. |
create()
Creates a new View.
| Name | Type | Description |
|---|---|---|
id |
STRING |
Optional viewer identifier which is used to select dedicated viewers. |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The new View |
viewer = View.create()
deregister()
This function is used to deregister from any registered event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to deregister from |
callback |
STRING |
The function name which was registered on the event |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully deregistered. False if event does not exist or callback wasn’t registered. |
installEditor()
Installs an editor for the specified iconic so that it can be edited in viewers. The editor is available after calling View.present. When an iconic is changed by an editor the View.OnChange event is published.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
iconicId |
STRING |
ID of the iconic for which to install an editor. |
View.installEditor(handle, "shape1")
present()
Updates registered viewers with changes to the View. This lets viewers - show iconics added with any of the View.add-functions - make editors (added with View.installEditor) available - remove (View.remove) or clear (View.clear) iconics. The Channel parameter is optional and defaults to LIVE. In overload situations, ASSURED means that present calls will be queued and LIVE means that older present calls will be discarded.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
channel |
ENUM Channel |
The channel on which to transmit the presented iconics. Default value is LIVE. |
View.present(handle, "LIVE")
rasterize()
Generates a 2D color image by rasterizing Shapes, Points, PixelRegions and Text as overlays into the pixels of a previously added image. The base image to rasterize into is taken to be the last added image using View.addImage or View.addHeightmap. Any subsequent calls to View.addShape, View.addPoint, View.addPixelRegion, View.addText, View.addPointCloud are used to add overlay graphics into the base image by modifying the pixel values in this image. This results in an image similar to what is shown in the viewer. Note however that this function does not have the full capacity as the external viewer typically has, so there will be differences. The main limitations are as follows: * 3D scenes cannot be reproduced, e.g., 3D pointcloud or mesh visualizations cannot be generated. * The resolution of the generated graphics is limited by the image rasterized into. * For text rendering there is a more limited set of ASCII characters supported compared to the external viewer. Moreover, rotated text is not currently supported. View.rasterize must be called prior to View.present as this latter function clears the internal list of objects inside the viewer instance. For each overlay iconic type there are also restrictions in terms of capacity compared to an external viewer. The support and limitations are as described below. Base image: The base image to draw on is defined to the last call by either by View.addImage or View.addHeightMap. Any pixel type is supported, e.g., UINT8, UINT16, FLOAT32. Grayscale images will be converted to RGB using a colormap. If the image is UINT8 without missing data a grayscale RGB image is generated. Otherwise the colormap 'JET' is used for conversion to RGB. To select a custom color map use the colormap ID in the View.ImageDecoration object when adding the image to the viewer. See details further down. The View.addHeightmap takes both a range image and an intensity image as input. To select which of these images to use there is a channelIndex input parameter to View.rasterize. Overlay support and restrictions: * PixelRegion - Fully supported using the provided decoration object. Full decoration support. * Shape - Supported as rasterized versions without any anti-aliasing. Full decoration support. * Point - Supported as rasterized versions without any anti-aliasing. Full decoration support. * Text - Supported with approximate mapping to the text rendered in the viewer. A limited ASCII-set is supported, i.e., not all characters will be rendered. Not all properties in the TextDecoration object are supported. * PointCloud - Partial support. Points are rendered over their x,y-coordinates in the image. The same colormaps are available as for the Image type. The following iconics are not supported: Mesh, Profile, Graph, Scan The colors for the rasterized image or pointcloud can be selected by the colormap ID in the View.ImageDecoration.setColormap or conversely in the View.PointCloudDecoration.setZColormap functions. This ID is mapped to the View.ColorMap.fromMap enums in the following order: 'AUTUMN', 'BLUE_WHITE_RED', 'COOL', 'GRAY', 'HOT', 'HSV', 'JET', 'RAINBOW', 'SPRING', 'SUMMER', 'THERMAL', 'TRAFFIC_LIGHT', 'WINTER', 'RGB'. Default is zero which attempts to mimic the default viewer behavior. Set 1 to get 'AUTUMN' and -1 to get an inverted 'AUTUMN' colorization.
color, jpeg, jpg, png, render, draw
Image.save, Object.save, View.addHeightMap, View.addPixelRegion, View.addPoint, View.addPointCloud, View.addShape, View.addText, View.addImage
| Name | Type | Description |
|---|---|---|
viewer |
HANDLE |
The viewer instance to rasterize. |
channelIndex |
INT |
Only relevant when View.addHeightMap was used to add the base image. Default is 0, which means that the heightmap/range image is used as base image. Set 1 to use the reflectance/intensity image instead. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
Rasterized color RGB image. Nil on failure. |
local image = View.rasterize(viewer)
register()
This function is used to register for any event of the handle.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
eventname |
STRING |
The event to register to |
callback |
STRING |
The function name to call on the event occurrence |
| Name | Type | Description |
|---|---|---|
success |
BOOL |
True if successfully registered. False if event does not exist. |
remove()
Removes the iconic with the given id from viewers when View.present is called.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
iconicId |
STRING |
Id of the iconic to remove. |
View.remove(handle, iconicId)
setDefaultDecoration()
Sets a default decoration, e.g., ShapeDecoration or ImageDecoration, that will be used in successive calls to view() and add() if the optional decoration argument is omitted.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
decoration |
OBJECT [API:DataFormat:] |
Decoration object that will be set as default. |
View.setDefaultDecoration(handle, decoration)
setFillColor()
Sets the fill color of the default ShapeDecoration. This function is deprecated, please use View.ShapeDecoration.setFillColor instead.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
red |
INT |
Red |
green |
INT |
Green |
blue |
INT |
Blue |
alpha |
INT |
Alpha |
View.setFillColor(handle, 255, 0, 0, 255)
setID()
Set the viewer identifier in order to select dedicated viewers.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
id |
STRING |
The identifier. |
View.setID(handle, "Viewer1")
setLineColor()
Sets the line color of the default ShapeDecoration. This function is deprecated, please use View.ShapeDecoration.setLineColor instead.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
red |
INT |
Red |
green |
INT |
Green |
blue |
INT |
Blue |
View.setLineColor(handle, 255, 0, 0)
setLineWidth()
Set the line width of the default ShapeDecoration. This function is deprecated, please use View.ShapeDecoration.setLineWidth instead.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
width |
INT |
The line thickness. |
View.setLineWidth(handle, 1)
uninstallEditor()
Removes the editor from the specified iconic. The editor is removed from viewers after View.present after calling View.present.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
iconicId |
STRING |
ID of the iconic for which to uninstall an editor. |
View.uninstallEditor(handle, "shape1")
updateCamera()
Updates the camera settings for the scene when View.present is called.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
camera |
OBJECT View.Camera |
The camera to set. |
View.updateCamera(handle, cam)
updateDecoration()
Updates the decoration of an already existing iconic when View.present is called. The type of the decoration must match the iconic.
View.GraphDecoration, View.ImageDecoration, View.MeshDecoration, View.PixelRegionDecoration, View.PointCloudDecoration, View.ScanDecoration, View.TextDecoration, View.present, View.ShapeDecoration
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
id |
STRING |
The identifier of the iconic. |
decoration |
OBJECT [API:DataFormat:] |
Decoration object that will be used for the update. |
View.updateDecoration(handle, "shape1", decoration)
updateTransform()
Updates the pose (position, orientation, scaling) with the given transform of an already existing iconic when View.present is called. It is up to the viewer what kind of transformations are valid.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
id |
STRING |
The identifier. |
transform |
OBJECT Transform |
Transformation applied to the given object. |
View.updateTransform(handle, "shape1", transform)
view()
Shows the given iconics (e.g. images, results, etc.) in the available viewers. If the decoration is omitted a default decoration is used. This function is deprecated. Use View.addXYZ and View.present instead. Reasons for deprecation: performance issues, type-safety, missing parent-id leads to usage of wrong coordinate-systems.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance to be used. |
iconics |
CONST_AUTO |
The iconic or list of iconics to be viewed. |
decoration |
CONST_OBJECT [API:DataFormat:] |
Optional decoration for the iconics. |
View.view(handle, iconics, decoration)
Events
OnChange
This event is published when an Iconic is modified using an editor in the Viewer. Apps can register to this event to react to the changes, for example to update their representation of the object with the changes from the viewer.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this view |
iconicId |
STRING |
ID of the modified iconic |
iconic |
OBJECT [API:DataFormat:] |
The modified iconic |
OnConnect
This event is published when a Viewer has connected to the View. Apps can register to this event to perform actions in response to the connection.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this view |
OnPointer
This event is published when a user has interacted with a Viewer using the select tool. Apps can register to this event to receive the id of the iconic under the pointer (if any) and the type of action.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
Instance handle of this view |
iconicId |
STRING |
The ID of the iconic under the pointer or an empty string if no iconic was hit. |
pointerActionType |
ENUM PointerActionType |
Pointer action type |
pointerType |
ENUM PointerType |
Pointer type |
View.Camera
Camera object that describes camera properties for the scene in the viewer. To be set with View.setCamera().
Overview
Functions
create()
Creates a new View.Camera
| Name | Type | Description |
|---|---|---|
camera |
HANDLE |
The new camera |
cam = View.Camera.create()
setPosition()
Set the position of the camera.
| Name | Type | Description |
|---|---|---|
camera |
HANDLE |
The instance to be used. |
posX |
FLOAT |
X |
posY |
FLOAT |
Y |
posZ |
FLOAT |
Z |
View.Camera.setPosition(cam, 0, -1, 1000)
setTarget()
Set the target-vector of the camera.
| Name | Type | Description |
|---|---|---|
camera |
HANDLE |
The instance to be used. |
posX |
FLOAT |
X |
posY |
FLOAT |
Y |
posZ |
FLOAT |
Z |
View.Camera.setTarget(cam, 0, 0, 0)
setUp()
Set the up-vector of the camera.
| Name | Type | Description |
|---|---|---|
camera |
HANDLE |
The instance to be used. |
posX |
FLOAT |
X |
posY |
FLOAT |
Y |
posZ |
FLOAT |
Z |
View.Camera.setUp(cam, 0, 0, 1)
View.ColorMap
Create a custom LINEAR color gradient in which colors are specified as entries in a vector with RGBA.
Functions
addStop()
Adds a color stop (value, R, G, B, A) to the ColorMap. If the value for a stop is outside the defined range, the stop is discarded.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
value |
FLOAT |
Represents a position between 0 and 1 at which a color for the gradient is defined. If the value equals the value of an existing color stop, the existing color stop is replaced. |
red |
INT |
Red value in range (0, 255). |
green |
INT |
Green value in range (0, 255). |
blue |
INT |
Blue value in range (0, 255). |
alpha |
INT |
Alpha/opacity component in range [0-255] (optional). |
View.ColorMap.addStop(handle, 255, 0, 0)
create()
Create a new ColorMap.
| Name | Type | Description |
|---|---|---|
rangeStart |
FLOAT |
Define the start of the value range. Default is 0.0 (optional). |
rangeStop |
FLOAT |
Define the stop of the value range. Default is 1.0 (optional). |
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The new ColorMap |
handle = View.ColorMap.create()
fromMap()
Create a gradient with predefined steps. The ColorMap will be cleared before.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
predefinedMap |
ENUM PredefinedColorMap |
Create a gradient with predefined steps. |
View.ColorMap.fromMap(handle, "RAINBOW")
setType()
A enum value indicating whether the ColorMap makes DISCRETE color jumps, or smooth LINEAR transition between color stops.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
type |
ENUM ColorMapType |
ColorMap type |
View.ColorMap.setType(handle, "DISCRETE")
toImage()
Convert the ColorMap to an image which represents the ColorMap from left to right.
| Name | Type | Description |
|---|---|---|
handle |
HANDLE |
The instance handle to use |
width |
INT |
Width of the image. |
height |
INT |
Height of the image. |
| Name | Type | Description |
|---|---|---|
image |
OBJECT Image |
The color map as image object. |
image = View.ColorMap.toImage(handle, 100, 200)
toString()
Get a user-friendly string description of the ColorMap.
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT View.ColorMap |
The ColorMap object. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the ColorMap. |
str = View.ColorMap.toString(handle)
View.GraphDecoration
Decoration object that describes visualization properties for graphs. For example, the graph type such as xy-plot (LINE) or histogram (BAR) can be set, as well as colors, text labels, size properties etc.
Overview
create(), setAspectRatio(), setAxisColor(), setAxisVisible(), setAxisWidth(), setBackgroundColor(), setBackgroundVisible(), setDrawSize(), setDynamicSizing(), setGraphColor(), setGraphType(), setGridColor(), setGridVisible(), setIndexCoordinates(), setLabelColor(), setLabelSize(), setLabels(), setLabelsVisible(), setPolarPlot(), setTicksVisible(), setTitle(), setTitleSize(), setXBounds(), setYBounds(), toString()
Functions
create()
Creates a new GraphDecoration object.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The new GraphDecoration |
graphDecoration = View.GraphDecoration.create()
setAspectRatio()
Sets the graphs aspect ratio.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
type |
ENUM AspectRatio |
The graphs aspect ratio, EQUAL, SQUARE or FIT. Default value is FIT. |
View.GraphDecoration.setAspectRatio(graphDecoration, "FIT")
setAxisColor()
Sets color of graph axes.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
red |
INT |
Red value in range [0,255] |
green |
INT |
Green value in range [0,255] |
blue |
INT |
Blue value in range [0,255] |
a |
INT |
Alpha value in range [0,255]. Optional, default value is 255. |
View.GraphDecoration.setAxisColor(graphDecoration, 255, 0, 0, 255)
setAxisVisible()
Sets whether to show or hide the axes.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
visible |
BOOL |
True if axis should be visible, default value is true. |
View.GraphDecoration.setAxisVisible(graphDecoration, false)
setAxisWidth()
Sets the graphs axis line width.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
width |
FLOAT |
Axis width. The default value is 0, which lets the viewer automatically decide the size.. |
View.GraphDecoration.setAxisWidth(graphDecoration, 2.5)
setBackgroundColor()
Sets background color of the plot.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
red |
INT |
Red value in range [0,255] |
green |
INT |
Green value in range [0,255] |
blue |
INT |
Blue value in range [0,255] |
a |
INT |
Alpha value in range [0,255]. Optional, default value is 255. |
View.GraphDecoration.setBackgroundColor(graphDecoration, 255, 0, 0, 255)
setBackgroundVisible()
Sets whether the background should be visible or not.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
visible |
BOOL |
True if background should be visible, default value is true. |
View.GraphDecoration.setBackgroundVisible(graphDecoration, false)
setDrawSize()
Sets the graph drawing size depending on the graph type set (size of points or width of lines or width of bars).
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
size |
FLOAT |
Draw size. The default value is 0, which lets the viewer automatically decide the size. |
View.GraphDecoration.setDrawSize(graphDecoration, 3)
setDynamicSizing()
Sets whether sizes should be dynamic and therefore independent from the zoom, or should be larger when zoomed in (default). Dynamic sizing also results in a dynamic tick distance, getting finer when zooming.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
dynamicSizing |
BOOL |
True if sizing should be dynamic instead of fixed, default value is false. |
View.GraphDecoration.setDynamicSizing(graphDecoration, true)
setGraphColor()
Sets color of the graph lines, dots or bars.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
red |
INT |
Red value in range [0,255] |
green |
INT |
Green value in range [0,255] |
blue |
INT |
Blue value in range [0,255] |
a |
INT |
Alpha value in range [0,255]. Optional, default value is 255. |
View.GraphDecoration.setGraphColor(graphDecoration, 255, 0, 0, 255)
setGraphType()
Sets the graph type to draw lines, dots or bars.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
type |
ENUM GraphType |
The graph type, DOT, LINE or BAR. Default value is LINE. |
View.GraphDecoration.setGraphType(graphDecoration, "BAR")
setGridColor()
Sets color of the grid lines.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
red |
INT |
Red value in range [0,255] |
green |
INT |
Green value in range [0,255] |
blue |
INT |
Blue value in range [0,255] |
a |
INT |
Alpha value in range [0,255]. Optional, default value is 255. |
View.GraphDecoration.setGridColor(graphDecoration, 255, 0, 0, 255)
setGridVisible()
Sets whether to show or hide the grid lines.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
visible |
BOOL |
True if grid should be visible, default value is true. |
View.GraphDecoration.setGridVisible(graphDecoration, false)
setIndexCoordinates()
Sets whether to use the index in the value vector as x value or use the supplied coordinate vector.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
indexAsX |
BOOL |
True if index rather then the coordinate should be used as x value, default value is false. |
View.GraphDecoration.setIndexCoordinates(graphDecoration, true)
setLabelColor()
Sets color of the text labels.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
red |
INT |
Red value in range [0,255] |
green |
INT |
Green value in range [0,255] |
blue |
INT |
Blue value in range [0,255] |
a |
INT |
Alpha value in range [0,255]. Optional, default value is 255. |
View.GraphDecoration.setLabelColor(graphDecoration, 255, 0, 0, 255)
setLabelSize()
Sets the text size of labels on the axes.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
size |
FLOAT |
Label text size. The default value is 0, which lets the viewer automatically decide the size. |
View.GraphDecoration.setLabelSize(graphDecoration, 3)
setLabels()
Sets the label text of the x and y axes.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
xLabel |
STRING |
x-axis text label, empty by default. |
yLabel |
STRING |
y-axis text label, empty by default. |
View.GraphDecoration.setLabels(graphDecoration, "Time [ms]", "Quantity")
setLabelsVisible()
Sets whether to show or hide the axes labels.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
visible |
BOOL |
True if labels should be visible, default value is true. |
View.GraphDecoration.setLabelsVisible(graphDecoration, false)
setPolarPlot()
Sets whether to use a polar or a linear visualization. If a polar visualization is chosen the coordinates of the graph will be used as angle (in radians) and the value as distance.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
polarVisualization |
BOOL |
True if a polar visualization should be used, default value is false. |
View.GraphDecoration.setPolarPlot(graphDecoration, true)
setTicksVisible()
Sets whether to show or hide the axes ticks.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
visible |
BOOL |
True if ticks should be visible, default value is true. |
View.GraphDecoration.setTicksVisible(graphDecoration, false)
setTitle()
Sets the title text.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
title |
STRING |
Title of the graph. Empty by default |
View.GraphDecoration.setTitle(graphDecoration, "Value over Time")
setTitleSize()
Sets the text size of the graph title.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
size |
FLOAT |
Title size. The default value is 0, which lets the viewer automatically decide the size. |
View.GraphDecoration.setTitleSize(graphDecoration, 3)
setXBounds()
Sets the graphs dimensions in x direction if lowerBound < upperBound, otherwise the dimension will be adjusted automatically
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
lowerBound |
FLOAT |
Lower bound. The default value is 0, which lets the viewer automatically decide the value. |
upperBound |
FLOAT |
Upper bound. The default value is 0, which lets the viewer automatically decide the value. |
View.GraphDecoration.setXBounds(graphDecoration, 0, 250)
setYBounds()
Sets the graphs dimensions in y direction if lowerBound < upperBound, otherwise the dimension will be adjusted automatically
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.GraphDecoration |
The instance to be used |
lowerBound |
FLOAT |
Lower bound. The default value is 0, which lets the viewer automatically decide the value. |
upperBound |
FLOAT |
Upper bound. The default value is 0, which lets the viewer automatically decide the value. |
View.GraphDecoration.setYBounds(graphDecoration, -250, 250)
toString()
Gets a user-friendly string description of the graph decoration.
| Name | Type | Description |
|---|---|---|
deco |
CONST_OBJECT View.GraphDecoration |
The instance to be used |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the graph decoration. |
str = View.GraphDecoration.toString(graphDecoration)
View.ImageDecoration
Decoration object that describes visualization properties for an image.
Overview
Functions
create()
Creates a new ImageDecoration. The default values for the decoration are: - range = [0,255] - colorMapID = 0
| Name | Type | Description |
|---|---|---|
imageDecorator |
OBJECT View.ImageDecoration |
The new ImageDecoration |
imageDecoration = View.ImageDecoration.create()
setColormap()
Sets an integer ID for the color map to use. An image viewer can have a predefined set of color maps to show scalar images false-coded in color for better contrast.
| Name | Type | Description |
|---|---|---|
imageDecorator |
OBJECT View.ImageDecoration |
The instance to be used. |
colorMapID |
INT |
An integer ID for the color map to use. The set of color maps available depends on the viewer component. |
View.ImageDecoration.setColormap(imageDecorator, 2)
setRange()
Sets the pixel value range to visualize. For example, if the range [100,500] is set, all pixel values below 100 should be mapped to black and all pixel values above 500 should be mapped to white. Please note that this function has no effect for UINT8 and RGB24 images.
| Name | Type | Description |
|---|---|---|
imageDecorator |
OBJECT View.ImageDecoration |
The instance to be used. |
minRange |
FLOAT |
The lower bound of the range to visualize. |
maxRange |
FLOAT |
The upper bound of the range to visualize. |
View.ImageDecoration.setRange(imageDecorator, 100, 500)
toString()
Gets a user-friendly string description of the image decoration.
| Name | Type | Description |
|---|---|---|
imageDecoration |
CONST_OBJECT View.ImageDecoration |
The decoration object. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the image decoration. |
str = View.ImageDecoration.toString(imageDecoration)
View.MeshDecoration
Decoration object that describes visualization properties for a mesh.
Overview
Functions
create()
Create a new MeshDecoration.
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.MeshDecoration |
The new MeshDecoration |
handle = View.MeshDecoration.create()
setSurfaceColor()
Set the color of the surface. This color is assigned to the ambient and diffuse material properties. Note that the alpha channel is currently unsupported and will have no effect.
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.MeshDecoration |
The instance to be used. |
r |
INT |
Red value in range (0,255). |
g |
INT |
Green value in range (0,255). |
b |
INT |
Blue value in range (0,255). |
a |
INT |
Alpha value in range (0,255). Currently unused. |
View.MeshDecoration.setSurfaceColor(handle, 0, 100, 0)
setVisibleFaces()
Set the triangle face to be rendered.
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.MeshDecoration |
The instance to be used. |
visibleFaces |
ENUM VisibleFaces |
Specifies what face(s) of the triangles to be rendered. By default both faces are rendered. |
View.MeshDecoration.setVisibleFaces(handle, "FRONT_AND_BACK")
toString()
Get a user-friendly string description of the mesh decoration.
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT View.MeshDecoration |
The decoration object. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the mesh decoration. |
str = View.MeshDecoration.toString(handle)
View.PixelRegionDecoration
Decoration object that describes visualization properties for a pixel region.
Overview
Functions
create()
Creates a new PixelRegionDecoration.
| Name | Type | Description |
|---|---|---|
pixelRegionDecorator |
OBJECT View.PixelRegionDecoration |
The new PixelRegionDecoration |
pixelRegionDecoration = View.PixelRegionDecoration.create()
setColor()
Sets the pixel region color.
| Name | Type | Description |
|---|---|---|
pixelRegionDecorator |
OBJECT View.PixelRegionDecoration |
The instance to be used. |
red |
INT |
Red value in range [0,255]. |
green |
INT |
Green value in range [0,255]. |
blue |
INT |
Blue value in range [0,255]. |
alpha |
INT |
Optional alpha value in range [0,255]. |
View.PixelRegionDecoration.setColor(pixelRegionDecorator, 255, 0, 0, 255)
toString()
Gets a user-friendly string description of the pixel region decoration.
| Name | Type | Description |
|---|---|---|
pixelRegionDecoration |
CONST_OBJECT View.PixelRegionDecoration |
The decoration object. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the pixel region decoration. |
str = View.PixelRegionDecoration.toString(pixelRegionDecoration)
View.PointCloudDecoration
Decoration object that describes visualization properties for a point cloud.
Overview
Functions
create()
Create a new PointCloudDecoration.
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.PointCloudDecoration |
The new PointCloudDecoration |
pointCloudDecoration = View.PointCloudDecoration.create()
setIntensityColormap()
Set an integer ID for the color map to use for the Intensity range (0 = gray scale).
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.PointCloudDecoration |
The instance to be used. |
colorMapID |
INT |
An integer ID for the color map to use. The set of color maps available depends on the viewer component. |
View.PointCloudDecoration.setIntensityColormap(handle, 2)
setIntensityRange()
Set the lower and upper bound of this component.
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.PointCloudDecoration |
The instance to be used. |
minValue |
FLOAT |
The lower bound of the intensity range to visualize. |
maxValue |
FLOAT |
The upper bound of the intensity range to visualize. |
View.PointCloudDecoration.setIntensityRange(handle, 0.1, 0.9)
setPointSize()
Set the size of displayed points.
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.PointCloudDecoration |
The instance to be used. |
pointSize |
FLOAT |
The size of a point |
View.PointCloudDecoration.setPointSize(handle, 2)
setXColormap()
Set an integer ID for the color map to use for the X range (0 = gray scale).
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.PointCloudDecoration |
The instance to be used. |
colorMapID |
INT |
An integer ID for the color map to use. The set of color maps available depends on the viewer component. |
View.PointCloudDecoration.setXColormap(handle, 2)
setXRange()
Set the lower and upper bound of this component.
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.PointCloudDecoration |
The instance to be used. |
minValue |
FLOAT |
The lower bound of the x range to visualize. |
maxValue |
FLOAT |
The upper bound of the x range to visualize. |
View.PointCloudDecoration.setXRange(handle, -100, 100)
setYColormap()
Set an integer ID for the color map to use for the Y range (0 = gray scale).
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.PointCloudDecoration |
The instance to be used. |
colorMapID |
INT |
An integer ID for the color map to use. The set of color maps available depends on the viewer component. |
View.PointCloudDecoration.setYColormap(handle, 2)
setYRange()
Set the lower and upper bound of this component.
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.PointCloudDecoration |
The instance to be used. |
minValue |
FLOAT |
The lower bound of the y range to visualize. |
maxValue |
FLOAT |
The upper bound of the y range to visualize. |
View.PointCloudDecoration.setYRange(handle, -100, 100)
setZColormap()
Set an integer ID for the color map to use for the Z range (0 = gray scale).
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.PointCloudDecoration |
The instance to be used. |
colorMapID |
INT |
An integer ID for the color map to use. The set of color maps available depends on the viewer component. |
View.PointCloudDecoration.setZColormap(handle, 2)
setZRange()
Set the lower and upper bound of this component.
| Name | Type | Description |
|---|---|---|
handle |
OBJECT View.PointCloudDecoration |
The instance to be used. |
minValue |
FLOAT |
The lower bound of the z range to visualize. |
maxValue |
FLOAT |
The upper bound of the z range to visualize. |
View.PointCloudDecoration.setZRange(handle, -100, 100)
toString()
Get a user-friendly string description of the point cloud decoration.
| Name | Type | Description |
|---|---|---|
handle |
CONST_OBJECT View.PointCloudDecoration |
The decoration object. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the point cloud decoration. |
str = View.PointCloudDecoration.toString(handle)
View.ShapeDecoration
Decoration object that describes visualization properties for shapes and points.
Overview
Functions
create()
Creates a new ShapeDecoration. The default values for the decoration are: - lineWidth = 1.0 - lineColor = (0, 0, 0, 255) - fillColor = (0, 0, 0, 0) - pointType = "DOT" - pointSize = 3.0 These values can be changed by using the corresponding functions.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.ShapeDecoration |
The new ShapeDecoration |
shapeDecoration = View.ShapeDecoration.create()
setFillColor()
Sets the fill color. It will be used to fill shape iconics.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.ShapeDecoration |
The instance to be used. |
red |
INT |
Red |
green |
INT |
Green |
blue |
INT |
Blue |
alpha |
INT |
Alpha |
View.ShapeDecoration.setFillColor(shapeDecoration, 255, 0, 0, 255)
setLineColor()
Sets the line color. It will be used for line, points and text iconics as well as stroke color for shape iconics.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.ShapeDecoration |
The instance to be used. |
red |
INT |
Red |
green |
INT |
Green |
blue |
INT |
Blue |
alpha |
INT |
Alpha |
View.ShapeDecoration.setLineColor(shapeDecoration, 255, 0, 0, 255)
setLineWidth()
Set the line width.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.ShapeDecoration |
The instance to be used. |
width |
FLOAT |
Width |
View.ShapeDecoration.setLineWidth(shapeDecoration, 2.3)
setPointSize()
Sets the point size for point iconics.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.ShapeDecoration |
The instance to be used. |
size |
FLOAT |
Size |
View.ShapeDecoration.setPointSize(shapeDecoration, 3.5)
setPointType()
Sets the display type for point iconics.
| Name | Type | Description |
|---|---|---|
deco |
OBJECT View.ShapeDecoration |
The instance to be used. |
type |
ENUM PointType |
The point type (DOT or CROSS). |
View.ShapeDecoration.setPointType(shapeDecoration, "CROSS")
toString()
Gets a user-friendly string description of the shape decoration.
| Name | Type | Description |
|---|---|---|
shapeDecoration |
CONST_OBJECT View.ShapeDecoration |
The decoration object. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the shape decoration. |
str = View.ShapeDecoration.toString(shapeDecoration)
View.TextDecoration
Decoration object that describes visualization properties for text overlays. Note that a viewer might not support all properties.
Overview
Functions
create()
Creates a new TextDecoration.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The new TextDecoration |
textDecorator = View.TextDecoration.create()
setBillboardActive()
Enable billboard mode. Default is off. When active, the text always faces the camera, and setRotation has no effect.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The instance to be used. |
active |
BOOL |
Set true to activate billboard. |
View.TextDecoration.setBillboardActive(textDecorator, true)
setBounds()
Sets the size of the enclosing bounding box. If set, the text is aligned inside these bounds. The box has its origin at position.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The instance to be used. |
width |
INT |
The bounds width. |
height |
INT |
The bounds height. |
View.TextDecoration.setBounds(textDecorator, 300, 100)
setColor()
Sets the text color.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The instance to be used. |
red |
INT |
Red value in range [0,255]. |
green |
INT |
Green value in range [0,255]. |
blue |
INT |
Blue value in range [0,255]. |
alpha |
INT |
Optional alpha value in range [0,255]. |
View.TextDecoration.setColor(textDecorator, 255, 0, 0, 255)
setFontFamily()
Sets the font style family of the text, e.g., sans serif, mono-spaced or serif font style. Depending on the platform the viewer runs on, a concrete font is selected within the given font family.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The instance to be used. |
fontFamily |
ENUM FontFamily |
Font family (SANSSERIF, MONOSPACE, SERIF). Default is SANSSERIF. |
View.TextDecoration.setFontFamily(textDecorator, "MONOSPACE")
setHorizontalAlignment()
Sets the horizontal alignment of the text relative to the given text position.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The instance to be used. |
horizontalAlignment |
ENUM HorizontalAlignment |
Horizontal alignment (LEFT, CENTER, RIGHT). Default is LEFT. |
View.TextDecoration.setHorizontalAlignment(textDecorator, "CENTER")
setLineSpacing()
Sets the line spacing in % of the text size.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The instance to be used. |
lineSpacing |
FLOAT |
The line spacing factor. The default value is 1.1. |
View.TextDecoration.setLineSpacing(textDecorator, 1.2)
setPosition()
Sets the text position.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The instance to be used. |
positionX |
FLOAT |
The text position x-coordinate. |
positionY |
FLOAT |
The text position y-coordinate. |
positionZ |
FLOAT |
The text position z-coordinate. Optional, only useful if a 3D viewer is used. |
View.TextDecoration.setPosition(textDecorator, 10, 10)
setRotation()
Sets the text rotation in radians around the given text position and around the given axis.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The instance to be used. |
rotation |
FLOAT |
Text rotation in radians. The default value is 0. |
axis |
FLOAT |
A 3d vector which describes the rotation axis. Default is {0,0,-1}. |
View.TextDecoration.setRotation(textDecorator, 1.5708, {0,1,0})
setSize()
Sets the text font size.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The instance to be used. |
fontSize |
FLOAT |
The text font size. The default value is 10. |
View.TextDecoration.setSize(textDecorator, 10)
setVerticalAlignment()
Sets the vertical alignment of the text relative to the given text position.
| Name | Type | Description |
|---|---|---|
textDecorator |
OBJECT View.TextDecoration |
The instance to be used. |
verticalAlignment |
ENUM VerticalAlignment |
Vertical alignment (BOTTOM, CENTER, TOP). Default is BOTTOM. |
View.TextDecoration.setVerticalAlignment(textDecorator, "CENTER")
toString()
Gets a human-friendly string description of the text decoration, containing all properties.
| Name | Type | Description |
|---|---|---|
textDecoration |
CONST_OBJECT View.TextDecoration |
The decoration object. |
| Name | Type | Description |
|---|---|---|
str |
STRING |
User-friendly description of the text decoration. |
str = View.TextDecoration.toString(textDecoration)
Enumerations
- B
- C
-
Cipher.Certificate.SigningRequest.Format Cipher.Key.Format Command.Client.AccessMode Command.Client.ByteOrder Command.Client.ProtocolType Connector.DigitalIn.DebounceMode Connector.DigitalIn.SignalLogic Connector.DigitalOut.ActivationMode Connector.DigitalOut.DelayedEvents.MeasurementUnit Connector.DigitalOut.DelayedEvents.StatusCode Connector.DigitalOut.PortOutputMode Connector.DigitalOut.SignalLogic Container.ItemTypes
- D
- E
-
Encoder.DecoderCountMode Encoder.DecoderPhases Encoder.Direction EncoderIncrementSources EthernetInterfaces
- F
-
FTPClient.SecurityProtocol FTPClient.TransferMode FieldBus.CreateMode FieldBus.TransmissionMode File.Archive.ZIP.Compression
- I
-
Image.BorderType Image.Calibration.Correction.CoordinateSystem Image.Calibration.Correction.CorrectionCropMode Image.ColorSpace Image.ConcatenationDirection Image.ContrastDifferenceMode Image.DifferenceMode Image.ExtremaType Image.GaussianFilterType Image.ImageType Image.InpaintMethod Image.InterpolationMethod Image.Matching.BackgroundClutterLevel Image.Matching.EdgeMatcherProcessingUnit Image.Matching.PatternMatcher.EdgeSensitivity Image.Matching.PatternVerifier.EdgeSensitivity Image.Matching.PointMatcher.PoseType Image.Matching.PointMatcher.PoseVariability Image.MetricType Image.MissingDataMethod Image.MorphologicalTransform Image.OCR.Halcon.AutoSegmenter.AutoSegmentationParameters Image.OCR.Halcon.FontClassifier.PreTrainedFonts Image.OCR.Halcon.ManualSegmenter.ManualSegmentationParameters Image.OutputGrid Image.PixelRegion.Filter.FeatureType Image.ProcessingDimension Image.Provider.Camera.V3TConfig2D.ImageTriggerMode Image.Provider.Camera.V3TConfig3D.ImageTriggerDelayUnit Image.Provider.Camera.V3TConfig3D.ImageTriggerMode Image.Provider.Camera.V3TConfig3D.PeakSelectionMode Image.Provider.Camera.V3TConfig3D.ProfileTriggerMode Image.Pyramid.DownsamplingMethod Image.Pyramid.ProcessingUnit Image.ShapeFitter.EdgeSelection IncrementPortConnectors
- L
- M
-
MachineLearning.DataSet.LabelType MachineLearning.KMeansClustering.InitMethod MachineLearning.NeuralNet.ActivationFunction MachineLearning.SupportVectorMachine.KernelType Monitor.App.AppStatus MountedDrives
- N
- O
-
OPCUA.AccessLevel OPCUA.DataType OPCUA.EventSeverity OPCUA.NodeClass OPCUA.NodeIDType OPCUA.NodeType OPCUA.ReferenceType OPCUA.Server.SecurityConfiguration.MessageSecurityMode OPCUA.Server.SecurityConfiguration.SecurityPolicy OPCUA.Server.SecurityConfiguration.UserTokenPolicy OPCUA.Server.Value.OptionalFieldState OPCUA.Server.Value.UnionField Object.DataFormat
- P
-
Point.NormType PointCloud.ColorMode PointCloud.Matching.Halcon.SurfaceMatcher.NormalComputationMethod PointCloud.toImageMode Profile.AggregateOperation Profile.ContrastDifferenceMode Profile.CoordinateType Profile.Curve.CurveType Profile.CurveFitter.CurveFitMode Profile.CurveFitter.CurveOutlierMarginType Profile.DifferenceMode Profile.DifferentiationOrder Profile.EdgeSide Profile.ExtremaType Profile.FillInvalidMethod Profile.ImageType Profile.Matching.PatternMatcher.ComparisonMode Profile.NoiseType Profile.SlopePolarity Profile.SortKey
- S
-
Script.Priority Script.Queue.Priority SerialComTypes SerialPorts Shape.OutlierMarginType Shape.PointFitMode Shape.ShapeType Shape3D.Shape3DType Shape3D.ShapePointFitMode Statistics.HistogramCompareMethod
- T
-
Transform.RotationOrder Transform.TransformType TriSpector.DeviceVariant
- V
-
View.Channel View.ColorMap.ColorMapType View.ColorMap.PredefinedColorMap View.GraphDecoration.AspectRatio View.GraphDecoration.GraphType View.MeshDecoration.VisibleFaces View.PointerActionType View.PointerType View.Present.Add.IconicType View.Present.Editor.EditorType View.Present.LogLevel View.ShapeDecoration.PointType View.TextDecoration.FontFamily View.TextDecoration.HorizontalAlignment View.TextDecoration.VerticalAlignment
Buttons
Cipher.Certificate.SigningRequest.Format
| Value | Name | Description |
|---|---|---|
PEM |
PKCS#10 PEM format |
Cipher.Key.Format
| Value | Name | Description |
|---|---|---|
PEM |
PEM format. PKI X.509 PEM format for public key, PKCS#8 PEM format for private key. |
Command.Client.AccessMode
| Value | Name | Description |
|---|---|---|
BY_NAME |
By name (Default) |
|
BY_INDEX |
By index |
Command.Client.ByteOrder
| Value | Name | Description |
|---|---|---|
BIG_ENDIAN |
Big-endian (Default) |
|
LITTLE_ENDIAN |
Little-endian |
Command.Client.ProtocolType
| Value | Name | Description |
|---|---|---|
COLA_A |
CoLa A (Default) |
|
COLA_B |
CoLa B |
|
COLA_2 |
CoLa 2 |
Connector.DigitalIn.DebounceMode
| Value | Name | Description |
|---|---|---|
TIME_MS |
Time in ms |
Time based with milliseconds value |
INCREMENT_TICK |
Increment in ticks |
Increment based with ticks as value |
Connector.DigitalIn.SignalLogic
| Value | Name | Description |
|---|---|---|
ACTIVE_HIGH |
Active high |
Active high signal logic is used |
ACTIVE_LOW |
Active low |
Active low signal logic is used |
Connector.DigitalOut.ActivationMode
| Value | Name | Description |
|---|---|---|
TIME_MS |
Time in ms |
Time based with milliseconds value |
INCREMENT_TICK |
Increment in ticks |
Increment based with ticks as value |
Connector.DigitalOut.DelayedEvents.MeasurementUnit
| Value | Name | Description |
|---|---|---|
INCREMENT_TICK |
Increment in ticks |
Value in encoder ticks |
TIME_US |
Time in us |
Value in microseconds |
Connector.DigitalOut.DelayedEvents.StatusCode
| Value | Name | Description |
|---|---|---|
OK |
OK |
The function executed correctly |
QUEUE_NOT_ENABLED |
Queue not enabled |
You have to run Connector.DigitalOut.DelayedEvents.enable before adding a new event |
QUEUE_FULL |
Queue full |
The queue is full |
LATE_EVENT |
Late event |
The added event has already passed |
UNORDERED_QUEUE |
Unordered queue |
The added event does not occur after the last event in the queue |
ILLEGAL_DURATION |
Illegal duration |
Illegal duration value specified |
Connector.DigitalOut.PortOutputMode
| Value | Name | Description |
|---|---|---|
HIGH_SIDE |
High-side |
Digital port works as high-side (PNP) output |
LOW_SIDE |
Low-side |
Digital port works as low-side (NPN) output |
PUSH_PULL |
Push-pull |
Digital port works as push-pull output |
Connector.DigitalOut.SignalLogic
| Value | Name | Description |
|---|---|---|
ACTIVE_HIGH |
Active high |
Active high signal logic is used |
ACTIVE_LOW |
Active low |
Active low signal logic is used |
Container.ItemTypes
The different types of which one item in the container can be. Matches the existing framework types.
| Value | Name | Description |
|---|---|---|
OBJECT |
object |
Only non-const object |
CONST_OBJECT |
const object |
Matches also non-const objects |
FLOAT |
float |
|
INT |
integer |
|
BOOL |
bool |
|
STRING |
string |
|
BINARY |
binary |
DigitalInPorts
| Value | Name | Description |
|---|---|---|
DI1 |
Digital In 1 |
|
DI2 |
Digital In 2 |
|
DI3 |
Digital In 3 |
|
DI4 |
Digital Input 4 |
Programmable IO 4 |
DI5 |
Digital Input 5 |
Programmable IO 5 |
DI6 |
Digital Input 6 |
Programmable IO 6 |
DI7 |
Digital Input 7 |
Programmable IO 7 |
DigitalLogic.Gate.Affinity
| Value | Name | Description |
|---|---|---|
SW |
Bound to software |
|
HW |
Bound to hardware |
DigitalOutPorts
| Value | Name | Description |
|---|---|---|
DO4 |
Digital Output 4 |
Programmable IO 4 |
DO5 |
Digital Output 5 |
Programmable IO 5 |
DO6 |
Digital Output 6 |
Programmable IO 6 |
DO7 |
Digital Output 7 |
Programmable IO 7 |
Encoder.DecoderCountMode
| Value | Name | Description |
|---|---|---|
BIDIRECTIONAL |
Bidirectional |
Counts up in Encoder forward / backward direction |
POSITIVE_MOVEMENT |
Positive Movement |
Counts up in Encoder forward direction / counts down in Encoder backward direction |
NEGATIVE_MOVEMENT |
Negative Movement |
Counts down in Encoder forward direction / counts up in Encoder backward direction |
FORWARD_MOVEMENT |
Forward Movement |
Counts up in Encoder forward direction / no count in Encoder backward direction |
BACKWARD_MOVEMENT |
Backward Movement |
No count in Encoder forward direction / counts up in Encoder backward direction |
Encoder.DecoderPhases
| Value | Name | Description |
|---|---|---|
SINGLE_PHASE |
Single Phase |
|
DUAL_PHASE |
Dual Phase |
Encoder.Direction
| Value | Name | Description |
|---|---|---|
FORWARD |
Forward Direction |
|
BACKWARD |
Backward Direction |
EncoderIncrementSources
| Value | Name | Description |
|---|---|---|
ENC1 |
ENC1 |
EthernetInterfaces
| Value | Name | Description |
|---|---|---|
ETH1 |
Ethernet |
The only available ethernet interface. |
FTPClient.SecurityProtocol
| Value | Name | Description |
|---|---|---|
NONE |
None |
Plain FTP (no transport security) |
FTPS_EXPLICIT |
FTPS explicit mode |
Require explicit FTP over TLS. Explicit mode: A plain FTP connection is established first, the client then requests to switch to TLS using the FTP command AUTH. This is the usual way to run FTPS. |
FTPS_IMPLICIT |
FTPS implicit mode |
Require implicit FTP over TLS. Implicit mode: A TLS session is established directly, without a previous negotiation via plain FTP. This is a more rare way to run FTPS. |
FTPClient.TransferMode
| Value | Name | Description |
|---|---|---|
ASCII |
ASCII mode |
|
BINARY |
Binary mode |
FieldBus.CreateMode
| Value | Name | Description |
|---|---|---|
EXPLICIT_OPEN |
Explicit Open |
Only create the handle, but do not automatically open communication. Communication must be started explicitly using the function open. |
AUTOMATIC_OPEN |
Automatic Open |
Create the handle and automatically open the communication |
FieldBus.TransmissionMode
| Value | Name | Description |
|---|---|---|
CONFIRMED_MESSAGING |
Confirmed Messaging |
Transmission mode using the SICK Confirmed Messaging protocol to transfer and fragment process data |
RAW |
Raw |
Transmission mode without any protocol |
File.Archive.ZIP.Compression
| Value | Name | Description |
|---|---|---|
STORE |
Store only, no compression |
|
FAST |
Fastest compression |
|
DEFAULT |
Default compression |
|
BEST |
Best compression, slowest |
Image.BorderType
| Value | Name | Description |
|---|---|---|
CONSTANT |
CONSTANT |
Example: iiii abcdef iiii |
REPLICATE |
REPLICATE |
Example: aaaa abcdef ffff |
REFLECT |
REFLECT |
Example: dcba abcdef fedc |
WRAP |
WRAP |
Example: cdef abcdef abcd |
Image.Calibration.Correction.CoordinateSystem
| Value | Name | Description |
|---|---|---|
CAMERA_PIXEL |
camera_pixel |
Pixel coordinates of the input camera image. |
CORRECTED_PIXEL |
corrected_pixel |
Pixel coordinates of the corrected output image. |
CORRECTED_WORLD |
corrected_world |
Image world coordinates of the corrected output image. |
EXTERNAL_WORLD |
external_world |
Point on the world ground plane (at z=0) as defined by the camera model, usually from a calibration pattern. |
Image.Calibration.Correction.CorrectionCropMode
| Value | Name | Description |
|---|---|---|
FULL |
full |
Full mode, creates an output containing all valid pixels and some zero-valued pixels where the corrected image is undefined. |
VALID |
valid |
Valid mode, creates an output containing only valid pixels, cropping out some values to create a rectangular output image. |
Image.ColorSpace
| Value | Name | Description |
|---|---|---|
COLORSPACE_RGB |
RGB |
RGB color space |
COLORSPACE_HSV |
HSV |
HSV color space |
COLORSPACE_LAB |
LAB |
LAB color space |
Image.ConcatenationDirection
| Value | Name | Description |
|---|---|---|
ABOVE |
ABOVE |
Concatenate image2 above image1 |
BELOW |
BELOW |
Concatenate image2 below image1 |
LEFT |
LEFT |
Concatenate image2 to the left of image1 |
RIGHT |
RIGHT |
Concatenate image2 to the right of image1 |
Image.ContrastDifferenceMode
| Value | Name | Description |
|---|---|---|
ONE |
one |
At least one point in the neighborhood should have the specified value margin to the extremal point. |
Image.DifferenceMode
| Value | Name | Description |
|---|---|---|
ABS |
ABS |
Absolute difference. |
SQUARE |
SQUARE |
Squared difference. |
Image.ExtremaType
| Value | Name | Description |
|---|---|---|
MAX |
MAX |
Local maxima |
MIN |
MIN |
Local minima |
Image.GaussianFilterType
| Value | Name | Description |
|---|---|---|
SIZE_SELECT |
SIZE_SELECT |
Choose implementation depending on filter size, default. |
TRUNCATED |
TRUNCATED |
Use convolution with a truncated kernel, this is faster for small filter sizes. |
RECURSIVE |
RECURSIVE |
Use a recursive filter to approximate the kernel. The run-time is independent of filter size and is recommended for large filter sizes. |
Image.ImageType
| Value | Name | Description |
|---|---|---|
INT8 |
int8 |
signed 8-bit integer |
INT16 |
int16 |
signed 16-bit integer |
INT32 |
int32 |
signed 32-bit integer |
INT64 |
int64 |
signed 64-bit integer |
UINT8 |
uint8 |
unsigned 8-bit integer |
UINT16 |
uint16 |
unsigned 16-bit integer |
UINT32 |
uint32 |
unsigned 32-bit integer |
UINT64 |
uint64 |
unsigned 64-bit integer |
FLOAT32 |
float32 |
32-bit floating-point |
FLOAT64 |
float64 |
64-bit floating-point |
RGB24 |
RGB24 |
24-bit RGB color image (stored in BGR byte order) |
Image.InpaintMethod
| Value | Name | Description |
|---|---|---|
NAVIER_STOKES |
NAVIER-STOKES |
Navier-Stokes equations based inpainting method. |
ALEXANDRU_TELEA |
ALEXANDRU TELEA |
An Image Inpainting Technique Based on the Fast Marching Method. |
Image.InterpolationMethod
| Value | Name | Description |
|---|---|---|
NEAREST |
nearest |
Resample using a nearest-neighbor interpolation |
LINEAR |
linear |
Resample using 2x2 bilinear interpolation |
Image.Matching.BackgroundClutterLevel
| Value | Name | Description |
|---|---|---|
LOW |
low |
Very few edges not belonging to the object. |
MEDIUM |
medium |
Some edges in the background not belonging to the object. |
HIGH |
high |
Many edges in the background not belonging to the object. |
Image.Matching.EdgeMatcherProcessingUnit
| Value | Name | Description |
|---|---|---|
CPU |
CPU |
Calculations will be done on the CPU. |
FPGA |
FPGA |
The FPGA will be used for hardware acceleration. |
Image.Matching.PatternMatcher.EdgeSensitivity
| Value | Name | Description |
|---|---|---|
HIGH |
High |
All pixels contribute to the verification. |
LOW |
Low |
Pixels close to edges are excluded. |
Image.Matching.PatternVerifier.EdgeSensitivity
| Value | Name | Description |
|---|---|---|
HIGH |
High |
All pixels contribute to the verification. |
LOW |
Low |
Pixels close to edges are excluded. |
Image.Matching.PointMatcher.PoseType
| Value | Name | Description |
|---|---|---|
RIGID |
Rigid |
Searches for objects whose image appears translated and rotated. The scale range is ignored in this mode. |
SIMILARITY |
Similarity |
Searches for objects whose image appears translated, rotated and uniformly scaled. |
AFFINE |
Affine |
Searches for objects whose image appears translated, rotated, non-uniformly scaled and skewed. |
HOMOGRAPHY |
Homography |
This is the most general transform, it allows e.g. out-of-plane rotation for flat objects. |
Image.Matching.PointMatcher.PoseVariability
| Value | Name | Description |
|---|---|---|
HIGH |
HIGH |
High pose variability: larger scale changes and visible perspective effects. |
LOW |
LOW |
Low pose variability: scale changes up to 30% and only small perspective effects. |
Image.MetricType
| Value | Name | Description |
|---|---|---|
ABS |
ABS |
Compute as L1 norm |
MAGNITUDE |
MAGNITUDE |
Compute as L2 norm |
Image.MissingDataMethod
| Value | Name | Description |
|---|---|---|
MAX |
MAX |
Setting missing data pixels to the maximum valid value in the neighborhood. |
MIN |
MIN |
Setting missing data pixels to the minimum valid value in the neighborhood. |
MEAN |
MEAN |
Setting missing data pixels to the mean of all valid values in the neighborhood. |
MEDIAN |
MEDIAN |
Setting missing data pixels to the median of all valid values in the neighborhood. |
EDGE |
EDGE |
Removing missing data by interpolating neighbor pixels in an edge-preserving way. |
Image.MorphologicalTransform
| Value | Name | Description |
|---|---|---|
ERODE |
ERODE |
Morphological erosion. |
DILATE |
DILATE |
Morphological dilation. |
OPEN |
OPEN |
Morphological opening |
CLOSE |
CLOSE |
Morphological closure |
GRADIENT |
GRADIENT |
Morphological gradient |
TOPHAT |
TOPHAT |
Morphological tophat |
BLACKHAT |
BLACKHAT |
Morphological blackhat |
Image.OCR.Halcon.AutoSegmenter.AutoSegmentationParameters
| Value | Name | Description |
|---|---|---|
MIN_CONTRAST |
min_contrast |
The minimal contrast the characters have to their surrounding background.List of values: integer or float value between 1 and 255 for byte images and between 1 and 65.535 for uint2 images. Default value: 15 |
POLARITY |
polarity |
'dark_on_light' if the text to be segmented is darker than its background, 'light_on_dark' if the text to be segmented is lighter than its background, and 'both' if both kinds of text are to be segmented. List of values: 'dark_on_light', 'light_on_dark' or 'both'. Default value: 'both' |
MIN_CHAR_HEIGHT |
min_char_height |
The minimal height of the characters in pixels. If text of arbitrary height is to be segmented, 'auto' may be passed. Note that 'min_char_height' refers to characters only. The height of punctuation marks or separators is not restricted by 'min_char_height'.List of values: integer or float value greater than or equal to 1. Default value: 'auto' |
MAX_CHAR_HEIGHT |
max_char_height |
The maximal height of the characters in pixels. If text of arbitrary height is to be segmented, 'auto' may be passed. Note that 'max_char_height' refers to characters only. The height of punctuation marks or separators is not restricted by 'max_char_height'.List of values: integer or float value greater than or equal to 1. Default value: 'auto' |
MIN_CHAR_WIDTH |
min_char_width |
The minimal width of the characters in pixels. If text of arbitrary width is to be segmented, 'auto' may be passed. Note that 'min_char_width' refers to characters only. The width of punctuation marks or separators is not restricted by 'min_char_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto' |
MAX_CHAR_WIDTH |
max_char_width |
The maximal width of the characters in pixels. If text of arbitrary width is to be segmented, 'auto' may be passed. Note that 'max_char_width' refers to characters only. The width of punctuation marks or separators is not restricted by 'max_char_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto' |
MIN_STROKE_WIDTH |
min_stroke_width |
The minimal stroke width of the characters in pixels. If the minimal stroke width is to be estimated within the text segmentation process automatically, 'auto' may be passed. Note that 'min_stroke_width' refers to characters only. The stroke width of punctuation marks or separators is not restricted by 'min_stroke_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto' |
MAX_STROKE_WIDTH |
max_stroke_width |
The maximal stroke width of the characters in pixels. If the maximal stroke width is to be estimated within the text segmentation process automatically, 'auto' may be passed. Note that 'max_stroke_width' refers to characters only. The stroke width of punctuation marks or separators is not restricted by 'max_stroke_width'.List of values: integer or float value greater than or equal to 1. Default value: 'auto' |
ELIMINATE_BORDER_BLOBS |
eliminate_border_blobs |
'true' if regions that are touching the border of the image domain should be discarded, otherwise 'false'.List of values: 'true','false'. Default value: 'false' |
RETURN_PUNCTUATION |
return_punctuation |
'true' if small punctuation marks that lie close to the base line of the corresponding text line (e.g. dots or commas) are to be returned. 'false' if no such punctuations should be returned.List of values: 'true','false'. Default value: 'true' |
RETURN_SEPARATORS |
return_separators |
'true' if separators such as a minus or the equality sign should be returned as well. 'false' if no separators should be returned.List of values: 'true','false'. Default value: 'true' |
ADD_FRAGMENTS |
add_fragments |
'true' if fragments, such as the dot on the 'i', should be added to the segmented characters, otherwise 'false'. Be aware, that this can cause noise to be added to the segmented characters.List of values: 'true','false'. Default value: 'true' |
TEXT_LINE_STRUCTURE |
text_line_structure |
To simplify the search for specific structures (e.g. dates or serial numbers) within the segmented text, it is possible to define text line structures. For each text line the distances between the characters are calculated, and based on these distances, the text line is divided into text blocks. Short characters such as '.', '_' and '-' are ignored in this process and treated as spaces. Furthermore, it is possible to define user specific separators which are also ignored. See the description of 'text_line_separators' for details. The text line structure is a string that contains the number of characters for every character block and spaces between these character blocks. For example, if the text to be found is a date with two characters for month, day, and year the structure would be '2 2 2'. If the year may consist of two or four characters, the structure would be '2 2 2-4', indicating that the last character block consists of two to four characters. It is possible to provide up to five structures to match by appending an index to the parameter name, e.g. 'text_line_structure_0', 'text_line_structure_1', etc. If 'text_line_structure' is set to an empty string '', the text to be found may have any structure. Please observe, that every text line structure which is found, is saved as in the text result even if they overlap. If the whole text line containing the text line structure is to be returned instead, it is possible to set 'return_whole_line' accordingly. Default value: '' |
TEXT_LINE_SEPARATORS |
text_line_separators |
A string containing the list of characters which are to be ignored in the process of finding text line structures, see 'text_line_structure' for further details. Please note, user specific separators need to be valid characters within the used OCR classifier. For example, if ':' and '\' are to be ignored, ':\\' should be passed. Please observe, that '\' escapes any special symbol to treat it as a literal, and hence '\\' needs to be passed to use '\' as a separator.List of values: '/', ':', ':\\', '\\/:', etc. Default value: ' ' |
RETURN_WHOLE_LINE |
return_whole_line |
'false' if only the segmented text line structures are to be returned as text lines. 'true' if each whole text line containing a text line structure is to be returned in text lines.List of values: 'true','false'. Default value: 'false' |
MLP_CLASSIFIER |
mlp_classifier |
The pre-trained font classifier used within findText for text segmentation. Default value: 'Industrial_Rej.omc' |
Image.OCR.Halcon.FontClassifier.PreTrainedFonts
| Value | Name | Description |
|---|---|---|
DOCUMENT_0_9A_Z_NOREJ |
Document_0-9A-Z_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
DOCUMENT_0_9A_Z_REJ |
Document_0-9A-Z_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
DOCUMENT_0_9_NOREJ |
Document_0-9_NoRej.omc |
Pre-trained font classifier for symbols: 0-9 |
DOCUMENT_0_9_REJ |
Document_0-9_Rej.omc |
Pre-trained font classifier for symbols: 0-9 |
DOCUMENT_A_ZPLUS_NOREJ |
Document_A-Z+_NoRej.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥ |
DOCUMENT_A_ZPLUS_REJ |
Document_A-Z+_Rej.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥ |
DOCUMENT_NOREJ |
Document_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥ |
DOCUMENT_REJ |
Document_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - = + < > . # $ % & ( ) @ * e £ ¥ |
DOTPRINT |
DotPrint.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . * : |
DOTPRINT_0_9PLUS |
DotPrint_0-9+.omc |
Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . * : |
DOTPRINT_0_9PLUS_NOREJ |
DotPrint_0-9+_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . * : |
DOTPRINT_0_9PLUS_REJ |
DotPrint_0-9+_Rej.omc |
Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . * : |
DOTPRINT_0_9 |
DotPrint_0-9.omc |
Pre-trained font classifier for symbols: 0-9 |
DOTPRINT_0_9A_Z |
DotPrint_0-9A-Z.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
DOTPRINT_0_9A_Z_NOREJ |
DotPrint_0-9A-Z_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
DOTPRINT_0_9A_Z_REJ |
DotPrint_0-9A-Z_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
DOTPRINT_0_9_NOREJ |
DotPrint_0-9_NoRej.omc |
Pre-trained font classifier for symbols: 0-9 |
DOTPRINT_0_9_REJ |
DotPrint_0-9_Rej.omc |
Pre-trained font classifier for symbols: 0-9 |
DOTPRINT_A_ZPLUS |
DotPrint_A-Z+.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / . * : |
DOTPRINT_A_ZPLUS_NOREJ |
DotPrint_A-Z+_NoRej.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / . * : |
DOTPRINT_A_ZPLUS_REJ |
DotPrint_A-Z+_Rej.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / . * : |
DOTPRINT_NOREJ |
DotPrint_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . * : |
DOTPRINT_REJ |
DotPrint_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . * : |
HANDWRITTEN_0_9 |
HandWritten_0-9.omc |
Pre-trained font classifier for symbols: 0-9 |
HANDWRITTEN_0_9_NOREJ |
HandWritten_0-9_NoRej.omc |
Pre-trained font classifier for symbols: 0-9 |
HANDWRITTEN_0_9_REJ |
HandWritten_0-9_Rej.omc |
Pre-trained font classifier for symbols: 0-9 |
INDUSTRIAL_0_9PLUS_NOREJ |
Industrial_0-9+_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / + . $ % * e £ ¥ |
INDUSTRIAL_0_9PLUS_REJ |
Industrial_0-9+_Rej.omc |
Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / + . $ % * e £ ¥ |
INDUSTRIAL_0_9A_Z_NOREJ |
Industrial_0-9A-Z_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
INDUSTRIAL_0_9A_Z_REJ |
Industrial_0-9A-Z_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
INDUSTRIAL_0_9_NOREJ |
Industrial_0-9_NoRej.omc |
Pre-trained font classifier for symbols: 0-9 |
INDUSTRIAL_0_9_REJ |
Industrial_0-9_Rej.omc |
Pre-trained font classifier for symbols: 0-9 |
INDUSTRIAL_A_ZPLUS_NOREJ |
Industrial_A-Z+_NoRej.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / + . $ % * e £ ¥ |
INDUSTRIAL_A_ZPLUS_REJ |
Industrial_A-Z+_Rej.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / + . $ % * e £ ¥ |
INDUSTRIAL_NOREJ |
Industrial_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / + . $ % * e £ ¥ |
INDUSTRIAL_REJ |
Industrial_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / + . $ % * e £ ¥ |
MICR |
MICR.omc |
Pre-trained font classifier. |
OCRA |
OCRA.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRA_0_9 |
OCRA_0-9.omc |
Pre-trained font classifier for symbols: 0-9 |
OCRA_0_9A_Z |
OCRA_0-9A-Z.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
OCRA_0_9A_Z_NOREJ |
OCRA_0-9A-Z_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
OCRA_0_9A_Z_REJ |
OCRA_0-9A-Z_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
OCRA_0_9_NOREJ |
OCRA_0-9_NoRej.omc |
Pre-trained font classifier for symbols: 0-9 |
OCRA_0_9_REJ |
OCRA_0-9_Rej.omc |
Pre-trained font classifier for symbols: 0-9 |
OCRA_A_ZPLUS |
OCRA_A-Z+.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRA_A_ZPLUS_NOREJ |
OCRA_A-Z+_NoRej.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRA_A_ZPLUS_REJ |
OCRA_A-Z+_Rej.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRA_NOREJ |
OCRA_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRA_REJ |
OCRA_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRB |
OCRB.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRB_0_9 |
OCRB_0-9.omc |
Pre-trained font classifier for symbols: 0-9 |
OCRB_0_9A_Z |
OCRB_0-9A-Z.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
OCRB_0_9A_Z_NOREJ |
OCRB_0-9A-Z_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
OCRB_0_9A_Z_REJ |
OCRB_0-9A-Z_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
OCRB_0_9_NOREJ |
OCRB_0-9_NoRej.omc |
Pre-trained font classifier for symbols: 0-9 |
OCRB_0_9_REJ |
OCRB_0-9_Rej.omc |
Pre-trained font classifier for symbols: 0-9 |
OCRB_A_ZPLUS |
OCRB_A-Z+.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRB_A_ZPLUS_NOREJ |
OCRB_A-Z+_NoRej.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRB_A_ZPLUS_REJ |
OCRB_A-Z+_Rej.omc |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRB_NOREJ |
OCRB_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
OCRB_PASSPORT |
OCRB_passport.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, + and < |
OCRB_PASSPORT_NOREJ |
OCRB_passport_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, + and < |
OCRB_PASSPORT_REJ |
OCRB_passport_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, + and < |
OCRB_REJ |
OCRB_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - ? ! / \ { } = + < > . # $ % & ( ) @ * e £ ¥ |
PHARMA |
Pharma.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . ( ) : |
PHARMA_0_9PLUS |
Pharma_0-9+.omc |
Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . ( ) : |
PHARMA_0_9PLUS_NOREJ |
Pharma_0-9+_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . ( ) : |
PHARMA_0_9PLUS_REJ |
Pharma_0-9+_Rej.omc |
Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / . ( ) : |
PHARMA_0_9 |
Pharma_0-9.omc |
Pre-trained font classifier for symbols: 0-9 |
PHARMA_0_9A_Z |
Pharma_0-9A-Z.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
PHARMA_0_9A_Z_NOREJ |
Pharma_0-9A-Z_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
PHARMA_0_9A_Z_REJ |
Pharma_0-9A-Z_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z |
PHARMA_0_9_NOREJ |
Pharma_0-9_NoRej.omc |
Pre-trained font classifier for symbols: 0-9 |
PHARMA_0_9_REJ |
Pharma_0-9_Rej.omc |
Pre-trained font classifier for symbols: 0-9 |
PHARMA_NOREJ |
Pharma_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . ( ) : |
PHARMA_REJ |
Pharma_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / . ( ) : |
SEMI |
SEMI.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - . |
SEMI_NOREJ |
SEMI_NoRej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - . |
SEMI_REJ |
SEMI_Rej.omc |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - . |
UNIVERSAL_0_9_NOREJ |
Universal_0-9_NoRej.occ |
Pre-trained font classifier for symbols: 0-9 |
UNIVERSAL_0_9_REJ |
Universal_0-9_Rej.occ |
Pre-trained font classifier for symbols: 0-9 |
UNIVERSAL_0_9PLUS_NOREJ |
Universal_0-9+_NoRej.occ |
Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥ |
UNIVERSAL_0_9PLUS_REJ |
Universal_0-9+_Rej.occ |
Pre-trained font classifier for symbols: 0-9, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥ |
UNIVERSAL_0_9A_Z_NOREJ |
Universal_0-9A-Z_NoRej.occ |
Pre-trained font classifier for symbols: 0-9, A-Z |
UNIVERSAL_0_9A_Z_REJ |
Universal_0-9A-Z_Rej.occ |
Pre-trained font classifier for symbols: 0-9, A-Z |
UNIVERSAL_0_9A_ZPLUS_NOREJ |
Universal_0-9A-Z+_NoRej.occ |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥ |
UNIVERSAL_0_9A_ZPLUS_REJ |
Universal_0-9A-Z+_Rej.occ |
Pre-trained font classifier for symbols: 0-9, A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥ |
UNIVERSAL_A_ZPLUS_NOREJ |
Universal_A-Z+_NoRej.occ |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥ |
UNIVERSAL_A_ZPLUS_REJ |
Universal_A-Z+_Rej.occ |
Pre-trained font classifier for symbols: A-Z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥ |
UNIVERSAL_NOREJ |
Universal_NoRej.occ |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥ |
UNIVERSAL_REJ |
Universal_Rej.occ |
Pre-trained font classifier for symbols: 0-9, A-Z, a-z, special characters. Available special characters: - / = + : < > . # $ % & ( ) @ * e £ ¥ |
Image.OCR.Halcon.ManualSegmenter.ManualSegmentationParameters
| Value | Name | Description |
|---|---|---|
CHAR_HEIGHT |
char_height |
Height of the characters in pixels. Refers to an uppercase character. List of values: integer or float value greater than or equal to 1. Default value: 30px |
CHAR_WIDTH |
char_width |
Width of the characters in pixels. Refers to an uppercase character. List of values: integer or float value greater than or equal to 1. Default value: 20px |
STROKE_WIDTH |
stroke_width |
Stroke width of the characters in pixels. List of values: integer or float value greater than or equal to 0. Default value: 4.0px |
BASE_LINE_TOLERANCE |
base_line_tolerance |
Maximum base line deviation of the characters (in percent of 'char_height'). Default value: 0.15 |
POLARITY |
polarity |
'dark_on_light' if the text to be segmented is darker than its background, otherwise 'light_on_dark'. List of values: 'dark_on_light' or 'light_on_dark'. Default value: 'dark_on_light' |
UPPERCASE_ONLY |
uppercase_only |
'true' if the text to be segmented contains uppercase characters or numbers only, otherwise 'false'. Default value: 'false' |
IS_DOTPRINT |
is_dotprint |
'true' if the text to be segmented is a dotprint, otherwise 'false'. Default value: 'false' |
IS_IMPRINTED |
is_imprinted |
'true' if the text to be segmented suffers of local changes of polarity due to reflections, otherwise 'false'. Default value: 'false' |
ELIMINATE_HORIZONTAL_LINES |
eliminate_horizontal_lines |
'true' if there are longer horizontal structures close to the text to be segmented, otherwise 'false'. Default value: 'false' |
ELIMINATE_BORDER_BLOBS |
eliminate_border_blobs |
'true' if regions that are touching the border of the image domain should be discarded, otherwise 'false'. Default value: 'false' |
MAX_LINE_NUM |
max_line_num |
Maximum number of lines to be found. Zero or negative values indicate no limitation. Setting 'max_line_num' to a low value may strongly improve the runtime of findText. Default value: no limitation |
RETURN_PUNCTUATION |
return_punctuation |
'true' if punctuation marks (e.g., dots or comma) should be added to the segmented characters. Default value: 'true' |
RETURN_SEPARATORS |
return_separators |
'true' if separators such as a minus or the equality sign should be added to the segmented characters. Default value: 'true' |
ADD_FRAGMENTS |
add_fragments |
'true' if fragments, such as the dot on the 'i', should be added to the segmented characters. Be aware, that this can cause noise to be added to the segmented characters. Default value: 'true' |
FRAGMENT_SIZE_MIN |
fragment_size_min |
minimum area of fragment regions that are added if 'add_fragments' is set to 'true'. List of values: integer value greater than or equal to 0. Default value: 1 |
TEXT_LINE_STRUCTURE |
text_line_structure |
To simplify the search for specific structures (e.g. dates or serial numbers) within the segmented text, it is possible to define text line structures. For each text line the distances between the characters are calculated, and based on these distances, the text line is divided into text blocks. Short characters such as '.', '_' and '-' are ignored in this process and treated as spaces. The text line structure is a string that contains the number of characters for every character block and spaces between these character blocks. For example, if the text to be found is a date with two characters for month, day, and year the structure would be '2 2 2'. If the year may consist of two or four characters, the structure would be '2 2 2-4', indicating that the last character block consists of two to four characters. It is possible to provide up to five structures to match by appending an index to the parameter name, e.g. 'text_line_structure_0', 'text_line_structure_1', etc. If 'text_line_structure' is set to an empty string '', the text to be found may have any structure. Please observe, that every text line structure which is found, is saved as in the text result even if they overlap. Default value: '' |
Image.OutputGrid
| Value | Name | Description |
|---|---|---|
SAME |
SAME |
The output is painted on the same pixel grid as the input. |
FULL |
FULL |
The origin and size of the output image is adjusted to fit the entire output. The world pixel size of the input image is used. |
Image.PixelRegion.Filter.FeatureType
| Value | Name | Description |
|---|---|---|
CENTROIDX |
centroid x |
Center of gravity in world coordinates, x part. See getCenterOfGravity. |
CENTROIDY |
centroid y |
Center of gravity in world coordinates, y part. See getCenterOfGravity. |
PIXELCOUNT |
pixel count |
Number of region pixels. See countPixels |
AREA |
area |
Region area in world units. See getArea. |
VOLUME |
volume |
Volume in world units. See getVolume. |
PERIMETER |
perimiter |
Region perimeter in world units. See getPerimeterLength. |
LARGESTSIDE |
largest side |
Largest side of a minimum area rectangle in world units (min-area rectangle fitted with accuracy 0.1 degrees). See getBoundingBoxOriented. |
SMALLESTSIDE |
smallest side |
Smallest side of a minimum area rectangle in world units (min-area rectangle fitted with accuracy 0.1 degrees). See getBoundingBoxOriented. |
MAJORAXIS |
major axis |
Length of major principal axis in world units. See getPrincipalAxes. |
MINORAXIS |
minor axis |
Length of minor principal axis in world units. See getPrincipalAxes. |
ROTATION |
rotation |
Rotation of major principal axis in world units. See getPrincipalAxes. |
ELONGATION |
elongation |
Ratio of major / minor axis lengths. See getElongation. |
CONVEXITY |
convexity |
Ratio of area / convex hull area. See getConvexity. |
COMPACTNESS |
compactness |
Compactness measure (4*PI*AREA) / PERIMETER^2. See getCompactness. |
HOLESCOUNT |
holes count |
Number of holes. See countHoles. |
TOUCHESBORDER |
touches border |
Touches border status (1 if region touches image border, 0 otherwise). See touchesImageBorder. |
AVERAGEVALUE |
average value |
Average image intensity or height map value within the region. See getStatistics. |
MINVALUE |
min value |
Minimum image intensity or height map value within the region. See getStatistics. |
MAXVALUE |
max value |
Maximum image intensity or height map value within the region. See getStatistics. |
STDDEVVALUE |
std value |
Standard deviation of image intensity or height map value within the region. See getStatistics. |
MEDIANVALUE |
median value |
Median of image intensity or height map value within the region. See getMedian. |
PERC10VALUE |
percentile 10 value |
10%-level (rank measure) of image intensity or height map value within the region (10% of all values are lower than this value). See getPercentiles. |
PERC90VALUE |
percentile 90 value |
90%-level (rank measure) of image intensity or height map value within the region (90% of all values are lower than this value). See getPercentiles. |
Image.ProcessingDimension
| Value | Name | Description |
|---|---|---|
ROW |
ROW |
Do processing row-wise |
COLUMN |
COLUMN |
Do processing column-wise |
Image.Provider.Camera.V3TConfig2D.ImageTriggerMode
| Value | Name | Description |
|---|---|---|
NONE |
None (Continous) |
Image acquisition is running continously |
SOFTWARE |
Software |
Image acquistion is triggered by software call |
Image.Provider.Camera.V3TConfig3D.ImageTriggerDelayUnit
| Value | Name | Description |
|---|---|---|
MS |
ms (milliseconds) |
Delay is specified in milliseconds |
MM |
mm (millimeters) |
Delay is specified in millimeters |
Image.Provider.Camera.V3TConfig3D.ImageTriggerMode
| Value | Name | Description |
|---|---|---|
NONE |
None (Continous) |
Image acquisition is running continously |
OBJECT |
Object |
Image acquisition is triggered by objects higher than the threshold determined by setObjectTriggerLine |
IO_3 |
I/O 3 |
Image acquisition is triggered by I/O 3 signal |
SOFTWARE |
Software |
Image acquistion is triggered by Image.Provider.Camera.trigger() |
Image.Provider.Camera.V3TConfig3D.PeakSelectionMode
| Value | Name | Description |
|---|---|---|
STRONGEST |
Strongest |
Use the point with the strongest intensity in each column as the laser peak |
TOP_MOST |
Top most |
Use the top most point with intensity greater than the configured laser threshold in each column as the laser peak |
BOTTOM_MOST |
Bottom most |
Use the bottom most point with intensity greater than the configured laser threshold when detecting the laser peak |
Image.Provider.Camera.V3TConfig3D.ProfileTriggerMode
| Value | Name | Description |
|---|---|---|
FREE_RUNNING |
Free running |
Acquire images at a constant speed, not using an encoder |
ENCODER |
Encoder |
Use a connected encoder to be able to handle variations in speed during image acquisition |
Image.Pyramid.DownsamplingMethod
| Value | Name | Description |
|---|---|---|
NEAREST |
nearest |
Downsample using nearest neighbor. |
LINEAR |
linear |
Downsample using 2x2 linear interpolation. |
GAUSSIAN |
gaussian |
Downsample using a Gaussian interpolation. |
Image.Pyramid.ProcessingUnit
| Value | Name | Description |
|---|---|---|
CPU |
CPU |
Calculations will be done on the CPU. |
FPGA |
FPGA |
The FPGA will be used for hardware acceleration. |
Image.ShapeFitter.EdgeSelection
| Value | Name | Description |
|---|---|---|
STRONGEST |
strongest |
Strongest edge found |
FIRST |
first |
First edge found |
LAST |
last |
Last edge found |
IncrementPortConnectors
| Value | Name | Description |
|---|---|---|
INC1 |
INC1 |
LEDs
| Value | Name | Description |
|---|---|---|
STATE_LED |
LED State |
Supported Colors: green |
RESULT_LED |
LED Result |
Supported Colors: red, green, blue |
LUA.math.Constants
| Value | Name | Description |
|---|---|---|
math.huge |
huge |
The value HUGE_VAL, a value larger than or equal to any other numerical value. |
math.pi |
pi |
The value of Pi (3.1415….). |
LUA.utf8.Constants
| Value | Name | Description |
|---|---|---|
utf8.charpattern |
UTF8 Pattern |
The pattern (a string, not a function) '[\0-\x7F\xC2-\xF4][\x80-\xBF]*' (see 6.4.1), which matches exactly one UTF-8 byte sequence, assuming that the subject is a valid UTF-8 string. |
Log.Level
| Value | Name | Description |
|---|---|---|
OFF |
Log nothing |
|
SEVERE |
Log only severe errors |
|
WARNING |
Log warnings and severe errors |
|
INFO |
Log infos, warnings and severe errors |
|
FINE |
Log fine, infos, warnings and severe errors |
|
FINER |
Log finer, fine, infos, warnings and severe errors |
|
FINEST |
Log finest, finer, fine, infos, warnings and severe errors |
|
ALL |
Log all messages |
MachineLearning.DataSet.LabelType
| Value | Name | Description |
|---|---|---|
CLASSIFICATION |
CLASSIFICATION |
Specify the use of discrete labels, this is what should be used when trying to separate distinct classes. |
REGRESSION |
REGRESSION |
Specify the use of floating point labels. This is useful when the labels can be sorted or meaningfully compared. |
MachineLearning.KMeansClustering.InitMethod
| Value | Name | Description |
|---|---|---|
RANDOM |
RANDOM |
Place start centers for clusters at random |
ESTIMATE |
ESTIMATE |
Try to estimate a good starting position |
MachineLearning.NeuralNet.ActivationFunction
| Value | Name | Description |
|---|---|---|
IDENTITY |
IDENTITY |
Identity activation function, eg. f(x) = x. |
SIGMOID |
SIGMOID |
Sigmoid activation function, eg. f(x) ~ tanh(x). |
GAUSSIAN |
GAUSSIAN |
Gaussian activation function, eg. f(x) ~ exp(-x^2). |
MachineLearning.SupportVectorMachine.KernelType
| Value | Name | Description |
|---|---|---|
LINEAR |
LINEAR |
Linear kernel. No mapping is done, linear discrimination (or regression) is done in the original feature space. It is the fastest option. K(x, y) = x^T * y. |
GAUSSIAN |
GAUSSIAN |
Radial basis function (RBF), a good choice in most cases. K(x, y) = e^{- |
x - |
Monitor.App.AppStatus
The different possible status of an app.
| Value | Name | Description |
|---|---|---|
UNKNOWN |
UNKNOWN |
|
RUNNING |
RUNNING |
|
STOPPED |
STOPPED |
|
CRASHED |
CRASHED |
MountedDrives
| Value | Name | Description |
|---|---|---|
/ram |
RAM |
|
/sdcard/0 |
SDCARD |
NTPClient.TimeSource
| Value | Name | Description |
|---|---|---|
MANUAL |
Manual |
Don’t update the time over NTP |
NTP |
NTP |
Update the time over NTP |
OPCUA.AccessLevel
Possibilities to access a VARIABLE node value
| Value | Name | Description |
|---|---|---|
READ |
Read |
The value is read only |
READ_WRITE |
ReadWrite |
The value can be read and written |
OPCUA.DataType
Enumeration of the supported OPC UA built-in data types
| Value | Name | Description |
|---|---|---|
BYTE_STRING |
ByteString |
An array of unsigned bytes |
BOOL |
Bool |
A boolean value |
BYTE |
Byte |
An unsigned byte |
SBYTE |
SByte |
A signed byte |
INT16 |
Int16 |
A 16 bit signed integer |
UINT16 |
UInt16 |
A 16 bit unsigned integer |
INT32 |
Int32 |
A 32 bit signed integer |
UINT32 |
UInt32 |
A 32 bit unsigned integer |
INT64 |
Int64 |
A 64 bit signed integer |
UINT64 |
UInt64 |
A 64 bit unsigned integer |
FLOAT |
Float |
A 32 bit IEEE-754 floating point number |
DOUBLE |
Double |
A 64 bit IEEE-754 floating point number |
STRING |
String |
An UTF-8 String |
STATUS_CODE |
StatusCode |
OPC UA StatusCode (see OPC UA specification part 4 (7.34)) |
DATE_TIME |
DateTime |
An instance in time (e.g., 1988-04-30T03:04:05Z; see OPC UA specification part 6 (5.2.2.5)) |
GUID |
Guid |
A globally unique identifier encoded as string (e.g., {72962B91-FA75-4AE6-8D28-B404DC7DAF63}, see OPC UA specification part 6 (5.2.2.6)) |
NODE_ID |
NodeId |
A node identifier encoded as string (e.g., "i=13" or "ns=12;s=Hello:World"; see OPC UA specification part 6 (5.3.1.10)) |
EXPANDED_NODE_ID |
ExpandedNodeId |
An expanded node identifier encoded as string (e.g., "svr=1;ns=2;s=Hello:World" or "svr=1;nsu=http://example.uri.com;s=Hello:World"; see OPC UA specification part 6 (5.3.1.11)) |
QUALIFIED_NAME |
QualifiedName |
A qualified name encoded as string of the form ">namespaceindex<:>name<" where namespace index is an unsigned 16 bit integer and name is a string (e.g., "1:some name"; see OPC UA specification part 3 (8.3)) |
LOCALIZED_TEXT |
LocalizedText |
A localized text as string of the form ">locale id<:>text<" where locale id is a locale string according to https://www.io.org/standard/57469.html and the actual localized text (e.g., "en-US:Hello World!" or "de:Hallo Welt!"; see OPC UA specification part 3 (8.4 and 8.5)) |
OPCUA.EventSeverity
Is mapped to OPC UA event severity (0 … 1000)
| Value | Name | Description |
|---|---|---|
HIGHEST |
Highest |
Highest severity (1000) |
HIGHER |
Higher |
Higher severity (900) |
HIGH |
High |
High severity (800) |
HIGHER_MEDIUM |
HigherMedium |
Higher than medium severity (650) |
MEDIUM |
Medium |
Medium severity (500) |
LOWER_MEDIUM |
LowerMedium |
Lower than medium severity (350) |
LOW |
Low |
Low severity (200) |
LOWER |
Lower |
Lower severity (100) |
LOWEST |
Lowest |
Lowest severity (0) |
OPCUA.NodeClass
All possible OPC UA node classes
| Value | Name | Description |
|---|---|---|
OBJECT |
Object |
Node representing an object |
VARIABLE |
Variable |
Node representing a (data) variable |
METHOD |
Method |
Node representing a method |
OBJECT_TYPE |
ObjectType |
Node representing an object type |
VARIABLE_TYPE |
VariableType |
Node representing a variable type |
REFERENCE_TYPE |
ReferenceType |
Node representing a reference type |
DATA_TYPE |
DataType |
Node representing a data type |
VIEW |
View |
Node representing a view |
OPCUA.NodeIDType
Possible types of OPC UA node ID
| Value | Name | Description |
|---|---|---|
NUMERIC |
Numeric |
An unsigned number is used; value range: 0-4294967295 |
STRING |
String |
A string should be used |
OPCUA.NodeType
All supported OPC UA standard node types
| Value | Name | Description |
|---|---|---|
BASE_DATA_VARIABLE_TYPE |
BaseDataVariableType |
The variable contains a potentially changeable value that represents data |
PROPERTY_TYPE |
PropertyType |
The variable contains unchangeable data that expresses a property of another node |
FOLDER_TYPE |
FolderType |
The object represents a folder |
OPCUA.ReferenceType
Possible types of references from one OPC UA node to another
| Value | Name | Description |
|---|---|---|
HAS_COMPONENT |
HasComponent |
The child node is a part of the parent node |
HAS_ORDERED_COMPONENT |
HasOrderedComponent |
The child node is a part of the parent node; the child nodes are always returned in the same order on discovery |
HAS_PROPERTY |
HasProperty |
The child node describes a property of the parent node, e.g. Input or Output arguments of a method |
HAS_SUBTYPE |
HasSubtype |
The child node is a subtype of the parent node |
HAS_EVENT_SOURCE |
HasEventSource |
The child node causes the parent node to generate an event |
HAS_NOTIFIER |
HasNotifier |
The child node causes the parent node to generate an event, but generates also events itself |
ORGANIZES |
Organizes |
The parent node is a folder which contains the child node |
GENERATES_EVENT |
GeneratesEvent |
The child node describes which event is generated by the parent node (ObjectType, VariableType, Method) |
ALWAYS_GENERATES_EVENT |
AlwaysGeneratesEvent |
The parent node (method) generates this event on each call |
HAS_TYPE_DEFINITION |
HasTypeDefinition |
The definition of the type of the parent node (variable or object) |
OPCUA.Server.SecurityConfiguration.MessageSecurityMode
This enum defines all possible message security modes to secure the message exchange between server and client. (cf. OPC UA specification, part 4, 7.15)
| Value | Name | Description |
|---|---|---|
NONE |
None |
Do not sign or encrypt the messages. |
SIGN |
Sign |
Sign the messages. |
SIGN_AND_ENCRYPT |
SignAndEncrypt |
Sign and encrypt the messages. |
OPCUA.Server.SecurityConfiguration.SecurityPolicy
This enum defines all security policies that can be used by a client to connect to the server.
| Value | Name | Description |
|---|---|---|
NONE |
None |
Use the http://opcfoundation.org/UA/SecurityPolicy#None security policy, i.e. do not use any security. |
BASIC_128_RSA_15 |
Basic128Rsa15 |
Use the http://opcfoundation.org/UA/SecurityPolicy#Basic128Rsa15 security policy. |
BASIC_256 |
Basic256 |
Use the http://opcfoundation.org/UA/SecurityPolicy#Basic256 security policy. |
BASIC_256_SHA_256 |
Basic256Sha256 |
Use the http://opcfoundation.org/UA/SecurityPolicy#Basic256Sha256 security policy. |
OPCUA.Server.SecurityConfiguration.UserTokenPolicy
Defines all possible user token policies / authentication modes that the client can use to establish a connection to the server. (cf. OPC UA specification, part 4, 7.36.1)
| Value | Name | Description |
|---|---|---|
ANONYMOUS |
Anonymous |
Use anonymous authentication. |
USERNAME |
Username |
Use user name and password for authentication. |
OPCUA.Server.Value.OptionalFieldState
| Value | Name | Description |
|---|---|---|
DISABLED |
DISABLED |
The field is not present |
ENABLED |
ENABLED |
The field ism present |
OPCUA.Server.Value.UnionField
| Value | Name | Description |
|---|---|---|
NO_FIELD |
NO_FIELD |
NO_FIELD |
FIELD_1 |
FIELD_1 |
FIELD_1 |
FIELD_2 |
FIELD_2 |
FIELD_2 |
FIELD_3 |
FIELD_3 |
FIELD_3 |
FIELD_4 |
FIELD_4 |
FIELD_4 |
FIELD_5 |
FIELD_5 |
FIELD_5 |
FIELD_6 |
FIELD_6 |
FIELD_6 |
FIELD_7 |
FIELD_7 |
FIELD_7 |
FIELD_8 |
FIELD_8 |
FIELD_8 |
FIELD_9 |
FIELD_9 |
FIELD_9 |
FIELD_10 |
FIELD_10 |
FIELD_10 |
FIELD_11 |
FIELD_11 |
FIELD_11 |
FIELD_12 |
FIELD_12 |
FIELD_12 |
FIELD_13 |
FIELD_13 |
FIELD_13 |
FIELD_14 |
FIELD_14 |
FIELD_14 |
FIELD_15 |
FIELD_15 |
FIELD_15 |
FIELD_16 |
FIELD_16 |
FIELD_16 |
FIELD_17 |
FIELD_17 |
FIELD_17 |
FIELD_18 |
FIELD_18 |
FIELD_18 |
FIELD_19 |
FIELD_19 |
FIELD_19 |
FIELD_20 |
FIELD_20 |
FIELD_20 |
FIELD_21 |
FIELD_21 |
FIELD_21 |
FIELD_22 |
FIELD_22 |
FIELD_22 |
FIELD_23 |
FIELD_23 |
FIELD_23 |
FIELD_24 |
FIELD_24 |
FIELD_24 |
FIELD_25 |
FIELD_25 |
FIELD_25 |
FIELD_26 |
FIELD_26 |
FIELD_26 |
FIELD_27 |
FIELD_27 |
FIELD_27 |
FIELD_28 |
FIELD_28 |
FIELD_28 |
FIELD_29 |
FIELD_29 |
FIELD_29 |
FIELD_30 |
FIELD_30 |
FIELD_30 |
FIELD_31 |
FIELD_31 |
FIELD_31 |
FIELD_32 |
FIELD_32 |
FIELD_32 |
Object.DataFormat
In what kind of format data should be read/written
| Value | Name | Description |
|---|---|---|
JSON |
JSON |
|
MSGPACK |
MessagePack |
Point.NormType
| Value | Name | Description |
|---|---|---|
L_1_NORM |
L-1-Norm |
Manhattan distance: |
x |
+ |
y |
+ |
z |
|
L_2_NORM |
L-2-Norm |
Euclidean distance: sqrt(x*x+y*y+z*z) |
L_INFINITY_NORM |
L-Infinity-Norm |
Maximum of absolute values: max( |
x |
, |
y |
, |
z |
) |
PointCloud.ColorMode
| Value | Name | Description |
|---|---|---|
INTENSITY |
Intensity |
Intensity values from 0.0 to 1.0 |
RGBA |
RGBA |
Red, Green, Blue, Alpha values from 0 to 255 |
PointCloud.Matching.Halcon.SurfaceMatcher.NormalComputationMethod
| Value | Name | Description |
|---|---|---|
MLS |
MLS |
Moving least-squares method for more accurate normal estimation. |
FAST |
Fast |
Fast approximate normal estimation method using a small neighborhood. |
PointCloud.toImageMode
| Value | Name | Description |
|---|---|---|
TOPMOST |
topmost |
Resolve point ambiguities by picking the upper point, i.e, prioritize points with higher z coordinate. |
BOTTOMMOST |
bottommost |
Resolve point ambiguities by picking the lower point,i.e, prioritize points with a lower z coordinate. |
Profile.AggregateOperation
| Value | Name | Description |
|---|---|---|
SUM |
sum |
Sum of values. |
MIN |
min |
Minimal value. |
MAX |
max |
Maximal value. |
MEAN |
mean |
Mean value. |
MEDIAN |
median |
Median value. |
Profile.ContrastDifferenceMode
| Value | Name | Description |
|---|---|---|
ONE |
one |
At least one point on each side in the neighborhood should have the specified value margin to the extremal point. |
ALL |
all |
All points in the neighborhood should have the specified value margin to the extremal point. |
Profile.CoordinateType
| Value | Name | Description |
|---|---|---|
IMPLICIT_1D |
implicit_1d |
Squared difference. |
EXPLICIT_1D |
explicit_1d |
Squared difference. |
IMPLICIT_2D |
implicit_2d |
Squared difference. |
EXPLICIT_2D |
explicit_2d |
Squared difference. |
Profile.Curve.CurveType
| Value | Name | Description |
|---|---|---|
POLYNOMIAL |
Polynomial |
Polynomial function. |
EXPONENTIAL |
Exponential |
Exponential function. |
GAUSSIAN |
Gaussian |
Gaussian function. |
Profile.CurveFitter.CurveFitMode
| Value | Name | Description |
|---|---|---|
LEAST_SQUARES |
least_squares |
Ordinary least squares. |
RANSAC |
ransac |
Ransac (random sampling with outlier rejection). |
Profile.CurveFitter.CurveOutlierMarginType
| Value | Name | Description |
|---|---|---|
RANK |
rank |
Rank-based margin, defines the rate of points to include. For example, A rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored. |
ABSOLUTE |
absolute |
Absolute outlier margin. |
Profile.DifferenceMode
| Value | Name | Description |
|---|---|---|
ABS |
abs |
Absolute difference. |
SQUARE |
square |
Squared difference. |
Profile.DifferentiationOrder
| Value | Name | Description |
|---|---|---|
FIRST |
first |
First order |
SECOND |
second |
Second order |
Profile.EdgeSide
| Value | Name | Description |
|---|---|---|
HIGH |
high |
Snap to the high side of the slope |
LOW |
low |
Snap to the low side of the slope |
CENTER |
center |
Snap to the slope center (point of maximal derivative) |
Profile.ExtremaType
| Value | Name | Description |
|---|---|---|
MAX |
max |
Local maxima |
MIN |
min |
Local minima |
Profile.FillInvalidMethod
| Value | Name | Description |
|---|---|---|
LINEAR |
linear |
Squared difference. |
NEIGHBOR_MIN |
neighbor_min |
Squared difference. |
NEIGHBOR_MAX |
neighbor_max |
Squared difference. |
NEIGHBOR_MEAN |
neighbor_mean |
Squared difference. |
Profile.ImageType
| Value | Name | Description |
|---|---|---|
INT8 |
int8 |
signed 8-bit integer |
INT16 |
int16 |
signed 16-bit integer |
INT32 |
int32 |
signed 32-bit integer |
INT64 |
int64 |
signed 64-bit integer |
UINT8 |
uint8 |
unsigned 8-bit integer |
UINT16 |
uint16 |
unsigned 16-bit integer |
UINT32 |
uint32 |
unsigned 32-bit integer |
UINT64 |
uint64 |
unsigned 64-bit integer |
FLOAT32 |
float32 |
32-bit floating-point |
FLOAT64 |
float64 |
64-bit floating-point |
Profile.Matching.PatternMatcher.ComparisonMode
| Value | Name | Description |
|---|---|---|
XCORRNORM |
xCorrNorm |
Cross correlation with normalization. |
SAD |
sad |
Sum of absolute difference. |
Profile.NoiseType
| Value | Name | Description |
|---|---|---|
NORMAL |
normal |
Normal distribution. |
UNIFORM |
uniform |
Uniform distribution. |
Profile.SlopePolarity
| Value | Name | Description |
|---|---|---|
POSITIVE |
positive |
Positive slope (low to high value) |
NEGATIVE |
negative |
Negative slope (high to low value) |
ANY |
any |
Either positive or negative |
Profile.SortKey
| Value | Name | Description |
|---|---|---|
BY_VALUE |
by_value |
Sort by value. |
BY_COORDINATE |
by_coordinate |
Sort by coordinate. |
Script.Priority
| Value | Name | Description |
|---|---|---|
LOW |
Low priority |
|
MEDIUM |
Medium priority |
|
HIGH |
High priority |
Script.Queue.Priority
The relative priority for scripts compared to other queues
| Value | Name | Description |
|---|---|---|
HIGH |
High |
|
MID |
Middle (Default) |
|
LOW |
Low |
SerialComTypes
| Value | Name | Description |
|---|---|---|
RS232 |
Default |
SerialPorts
| Value | Name | Description |
|---|---|---|
SER1 |
SER1 |
This serial interface supports SerialType RS232 |
Shape.OutlierMarginType
| Value | Name | Description |
|---|---|---|
ABSOLUTE |
absolute |
Absolute outlier margin, defined in world coordinate units (typically mm). |
RANK |
rank |
Rank-based margin, defines the rate of points to include. For example, A rank margin of 0.7 means that the best 70% of all points are included and the rest are ignored. |
Shape.PointFitMode
| Value | Name | Description |
|---|---|---|
LEASTSQUARES |
leastsquares |
Ordinary least squares |
RANSAC |
ransac |
Ransac (random sampling with outlier rejection) |
ADAPTIVE |
adaptive |
Ransac with rank-margin. This mode is deprecated and may be removed in a future version. Please use RANSAC and call setOutlierMargin with the margin type set to RANK instead. |
TRIMMED |
trimmed |
Two-stage least squares fitting. The second stage uses only points within the margin around the fitted shape of the first stage. |
Shape.ShapeType
| Value | Name | Description |
|---|---|---|
LINE |
Line |
Line shape (infinite length) |
LINE_SEGMENT |
Line segment |
Line segment shape |
POLYLINE |
Polyline |
Polyline shape, open or closed |
RECTANGLE |
Rectangle |
Rectangle shape (possibly rotated) |
CIRCLE |
Circle |
Circle shape |
ELLIPSE |
Ellipse |
Ellipse shape |
ARC |
Arc |
Arc shape, i.e. a part of a circle contour limited by two angles |
SECTOR |
Sector |
Sector shape enclosing a region limited by two angles, an inner and an outer radius |
Shape3D.Shape3DType
| Value | Name | Description |
|---|---|---|
PLANE |
Plane |
Plane (with infinite size) |
LINE |
Line |
Line in 3D (infinite length) |
LINE_SEGMENT |
Line segment |
Line segment in 3D |
RECTANGLE |
Rectangle |
2D rectangle in 3D space |
CIRCLE |
Circle |
2D circle in 3D space |
ELLIPSE |
Ellipse |
2D ellipse in 3D space |
POLYGON |
Polygon |
A closed planar 2D polygon in 3D space |
BOX |
Box |
Solid 3D box |
CYLINDER |
Cylinder |
Solid cylinder |
ELLIPTIC_CYLINDER |
EllipticCylinder |
Solid elliptic cylinder (elliptic base area extended with a height) |
CONE |
Cone |
A 3D cone |
SPHERE |
Sphere |
Sphere |
POLYLINE |
Polyline |
An open polyline in 3D |
Shape3D.ShapePointFitMode
| Value | Name | Description |
|---|---|---|
LEASTSQUARES |
leastsquares |
Ordinary least squares |
RANSAC |
ransac |
Ransac (random sampling with outlier rejection) |
TRIMMED |
trimmed |
Two-stage least squares fitting. The second stage uses only points within the margin around the fitted shape of the first stage. |
Statistics.HistogramCompareMethod
| Value | Name | Description |
|---|---|---|
L1 |
L1 norm |
Sum of absolute differences |
L2 |
L2 norm |
Euclidean norm, square root of sum of square differences |
MAXDIFF |
Maximal difference |
Maximal difference between corresponding bins (L-infinity norm) |
CHI2 |
Chi-square statistic |
Chi-square statistic (normalized sum of squares). This is the default method and should work well in most cases. |
KLDIV |
Kullback-Leibler divergence |
Kullback-Leibler divergence: sum(p[i] * log(p[i] / q[i]) |
Transform.RotationOrder
| Value | Name | Description |
|---|---|---|
XYZ |
XYZ |
Rotation first around the world x-axis, then the world y-axis and last the world z-axis. |
ZYX |
ZYX |
Rotation first around the world z-axis, then the world y-axis and last the world x-axis. |
ZYZ |
ZYZ |
Rotation first around the world z-axis, then the world y-axis and last the world z-axis. |
Transform.TransformType
| Value | Name | Description |
|---|---|---|
IDENTITY |
Identity |
Identity transform |
TRANSLATION |
Translation |
A translation transform shifts an object along the x, y and z axes |
RIGID |
Rigid |
A rigid transform rotates and translates an object |
SIMILARITY |
Similarity |
A similarity transform scales, rotates and translates an object |
AFFINE |
Affine |
An affine transform shears, scales, rotates and translates and object |
HOMOGRAPHY |
Homography |
A homography transform, also known as a projective transform, is the most general linear transform. It includes affine, similarity and rigid transforms as special cases. |
TriSpector.DeviceVariant
| Value | Name | Description |
|---|---|---|
TriSpectorP 1008 |
TriSpectorP 1008 |
TriSpectorP 1008 device variant |
TriSpectorP 1030 |
TriSpectorP 1030 |
TriSpectorP 1030 device variant |
TriSpectorP 1060 |
TriSpectorP 1060 |
TriSpectorP 1060 device variant |
View.Channel
| Value | Name | Description |
|---|---|---|
LIVE |
LIVE |
In case of queues on the channel, only the latest presented iconics will be delivered. This is the default value for View.present(). |
ASSURED |
ASSURED |
None of the presented iconics will be discarded. |
View.ColorMap.ColorMapType
| Value | Name | Description |
|---|---|---|
LINEAR |
LINEAR |
Smooth linear transition between color stops |
DISCRETE |
DISCRETE |
Discrete color jumps at the color stops |
View.ColorMap.PredefinedColorMap
| Value | Name | Description |
|---|---|---|
AUTUMN |
AUTUMN |
red → yellow |
BLUE_WHITE_RED |
BLUE_WHITE_RED |
blue → white → red |
COOL |
COOL |
aqua → fuchsia |
GRAY |
GRAY |
black → white |
HOT |
HOT |
black → red → yellow → white |
HSV |
HSV |
red → yellow → green → aqua → blue → fuchsia → red |
JET |
JET |
blue → aqua → green → yellow → red |
RAINBOW |
RAINBOW |
red → fuchsia → blue → aqua → green → yellow → red |
SPRING |
SPRING |
fuchsia → yellow |
SUMMER |
SUMMER |
deep sea → lemon |
THERMAL |
THERMAL |
black → pink → orange → yellow → white |
TRAFFIC_LIGHT |
TRAFFIC_LIGHT |
red → yellow → green |
WINTER |
WINTER |
blue → spring green |
RGB |
RGB |
red → green → blue |
View.GraphDecoration.AspectRatio
| Value | Name | Description |
|---|---|---|
EQUAL |
EQUAL |
Equal aspect ratio (both axis has the same scaling) |
SQUARE |
SQUARE |
Square aspect ratio |
FIT |
FIT |
Fitting the viewer |
View.GraphDecoration.GraphType
| Value | Name | Description |
|---|---|---|
DOT |
DOT |
Dot graph |
LINE |
LINE |
Line graph |
BAR |
BAR |
Bar graph |
View.MeshDecoration.VisibleFaces
| Value | Name | Description |
|---|---|---|
FRONT |
FRONT |
Renders the front faces. A front face exists if the triangle vertices, in order, rotate clockwise around the triangle’s center. |
BACK |
BACK |
Renders the back faces. A back face exists if the triangle vertices, in order, rotate counter-clockwise around the triangle’s center. |
FRONT_AND_BACK |
FRONT_AND_BACK |
Renders both front and back faces. |
NONE |
NONE |
Does not render the triangle faces. It can be used for example if only the vertex points are rendered. |
View.PointerActionType
| Value | Name | Description |
|---|---|---|
CLICKED |
CLICKED |
|
DOWN |
DOWN |
|
UP |
UP |
View.PointerType
| Value | Name | Description |
|---|---|---|
PRIMARY |
PRIMARY |
|
SECONDARY |
SECONDARY |
|
MIDDLE |
MIDDLE |
View.Present.Add.IconicType
| Value | Name | Description |
|---|---|---|
HEIGHTMAP |
HEIGHTMAP |
Add heightmap type |
IMAGE |
IMAGE |
Add image type |
PIXEL_REGION |
PIXEL_REGION |
Add pixel region type |
POINT_CLOUD |
POINT_CLOUD |
Add point cloud type |
SHAPE |
SHAPE |
Add shape type |
TEXT |
TEXT |
Add text type |
PROFILE |
PROFILE |
Add profile type |
POLAR_SCAN |
POLAR_SCAN |
Add polar scan type |
MESH |
MESH |
Add mesh type |
View.Present.Editor.EditorType
| Value | Name | Description |
|---|---|---|
INSTALL |
INSTALL |
Install editor |
UNINSTALL |
UNINSTALL |
Uninstall editor |
View.Present.LogLevel
| Value | Name | Description |
|---|---|---|
INFO |
INFO |
Log level for info |
WARNING |
WARNING |
Log level for warnings |
ERROR |
ERROR |
Log level for errors |
View.ShapeDecoration.PointType
| Value | Name | Description |
|---|---|---|
DOT |
DOT |
a dot to present the point |
CROSS |
CROSS |
a cross to present the point |
View.TextDecoration.FontFamily
| Value | Name | Description |
|---|---|---|
SANSSERIF |
SANSSERIF |
Sans Serif font, e.g., Arial, Helvetica style. |
MONOSPACE |
MONOSPACE |
Mono-spaced font, e.g., Courier style. |
SERIF |
SERIF |
Serif font, e.g., Times New Roman style. |
View.TextDecoration.HorizontalAlignment
| Value | Name | Description |
|---|---|---|
LEFT |
LEFT |
Align text to the left of the given position. |
CENTER |
CENTER |
Align text centered horizontally relative to given position. |
RIGHT |
RIGHT |
Align text to the right of the given position. |
JUSTIFY |
JUSTIFY |
Align text in a justified mode (stretch spaces to fill the bound’s width). |
View.TextDecoration.VerticalAlignment
| Value | Name | Description |
|---|---|---|
BOTTOM |
BOTTOM |
Align bottom of text with the given position. |
CENTER |
CENTER |
Align center of text with the given position. |
TOP |
TOP |
Align top of text with the given position. |
Data formats
- C
- D
- E
- I
-
Image Image.Calibration.CameraModel Image.Fixture Image.Fixture3D Image.Matching.EdgeMatcher Image.Matching.EdgeMatcher3D Image.Matching.PointMatcher Image.PixelRegion
- M
- P
-
Parameters.Node Parameters.Node.Array Parameters.Node.Struct Parameters.Node.Variant Point Point2D Point3D Point3D_32 PointCloud PointCloud.XYZI Profile Profile.Curve Profile.Curve.Exponential Profile.Curve.Gaussian Profile.Curve.Polynomial Profile.Log
- S
-
SensorData Shape Shape.Arc Shape.Circle Shape.Composite Shape.Ellipse Shape.Line Shape.LineSegment Shape.PolyLine Shape.Rectangle Shape.Sector Shape3D Shape3D.Box Shape3D.Circle Shape3D.Cone Shape3D.Cylinder Shape3D.Ellipse Shape3D.EllipticCylinder Shape3D.Line Shape3D.LineSegment Shape3D.Plane Shape3D.Polygon Shape3D.Polyline Shape3D.Rectangle Shape3D.Sphere
- T
- V
-
View.Camera View.ColorMap View.GraphDecoration View.GraphDecoration.ASPECTRATIO View.GraphDecoration.GRAPHTYPE View.GraphDecoration.RGBA View.ImageDecoration View.ImageDecoration.DataRange View.MeshDecoration View.MeshDecoration.VisibleFaces View.PixelRegionDecoration View.PixelRegionDecoration.RGBA View.PointCloudDecoration View.Present.Add View.Present.Clear View.Present.Editor View.Present.Remove View.Present.UpdateDecoration View.Present.UpdateTransform View.ShapeDecoration View.ShapeDecoration.Pixel.RGBA View.ShapeDecoration.PointType View.TextDecoration View.TextDecoration.Bounds View.TextDecoration.FontFamily View.TextDecoration.FontWeight View.TextDecoration.HorizontalAlignment View.TextDecoration.RGBA View.TextDecoration.VerticalAlignment
Container
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Content">
<array>
<item>
<struct>
<item name="Key">
<string/>
</item>
<item name="Type">
<string/>
</item>
<item name="IsVector">
<bool/>
</item>
<item name="Value">
<any_of>
<item>
<int signed="true" width="64"/>
</item>
<item>
<int signed="false" width="64"/>
</item>
<item>
<float width="64"/>
</item>
<item>
<bool/>
</item>
<item>
<string/>
</item>
<item>
<polymorphic/>
</item>
<item>
<array>
<item>
<int signed="true" width="64"/>
</item>
</array>
</item>
<item>
<array>
<item>
<int signed="false" width="64"/>
</item>
</array>
</item>
<item>
<array>
<item>
<float width="64"/>
</item>
</array>
</item>
<item>
<array>
<item>
<bool/>
</item>
</array>
</item>
<item>
<array>
<item>
<string/>
</item>
</array>
</item>
<item>
<array>
<item>
<polymorphic/>
</item>
</array>
</item>
</any_of>
</item>
</struct>
</item>
</array>
</item>
</struct>
</item>
{
"class" : "Container",
"data" : {
"Content" : [ {
"Key" : "valKey1",
"Type" : "int",
"IsVector" : false,
"Value" : 5
}, {
"Key" : "valKey2",
"Type" : "string",
"IsVector" : false,
"Value" : "stringval"
}, {
"Key" : "valKey3",
"Type" : "object",
"IsVector" : false,
"Value" : {
"class" : "MyObject",
"data" : {
"somevalue" : "stringval"
}
}
}, {
"Key" : "valKey4",
"Type" : "float",
"IsVector" : true,
"Value" : [ 1.0, 2.0, 3.0 ]
} ]
}
}
DateTime
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="ExtendedUnixTime" desc="Unix time plus fraction of a second">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "DateTime",
"data" : {
"ExtendedUnixTime" : 1.570779685528E9
}
}
EncoderData
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Position" desc="Encoder position incremental value">
<int signed="false" width="32"/>
</item>
<item name="Speed" desc="Speed in m/s">
<float width="32"/>
</item>
<item name="SystemIncrement" desc="System increment value; application specific">
<int signed="false" width="32"/>
</item>
<item name="TimestampUTC" desc="UTC time stamp in floating-point seconds">
<float width="64"/>
</item>
<item name="TimestampUS" desc="Application specific, relative time stamp in microseconds">
<int signed="false" width="64"/>
</item>
<item name="xValue" desc="Corresponding x-value if available. Application specific">
<int signed="false" width="32"/>
</item>
</struct>
</item>
{
"class" : "EncoderData",
"data" : {
"Position" : 0,
"Speed" : 0,
"SystemIncrement" : 0,
"TimestampUTC" : 0,
"TimestampUS" : 0,
"xValue" : 0
}
}
Image
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="PixelSize" desc="Size of the image pixel in some coordinate system (application defined). Usage is optional.">
<data_format_ref name="Point3D"/>
</item>
<item name="Origin" desc="Application defined coordinate of the top left pixel. Usage is optional.">
<data_format_ref name="Point3D"/>
</item>
<item name="HandleZeroPixels" desc="How pixels with value zero are interpreted">
<any_of>
<item desc="Pixels with value 0 are real pixels">
<string value="Default"/>
</item>
<item desc="Pixels with value 0 indicate missing data and are no 'real' value">
<string value="MissingData"/>
</item>
</any_of>
</item>
<item name="Data">
<struct>
<item name="ImageType">
<any_of>
<item>
<string value="uint8"/>
</item>
<item>
<string value="uint16"/>
</item>
<item>
<string value="uint32"/>
</item>
<item>
<string value="uint64"/>
</item>
<item>
<string value="int8"/>
</item>
<item>
<string value="int16"/>
</item>
<item>
<string value="int32"/>
</item>
<item>
<string value="int64"/>
</item>
<item>
<string value="float32"/>
</item>
<item>
<string value="float64"/>
</item>
<item>
<string value="RGB24"/>
</item>
</any_of>
</item>
<item name="Width">
<int signed="true" width="32"/>
</item>
<item name="Height">
<int signed="true" width="32"/>
</item>
<item name="Pixels">
<any_of>
<item>
<big_data_array>
<element_type name="uint8" desc="The pixel content"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="uint16" desc="The pixel content"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="uint32" desc="The pixel content"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="uint64" desc="The pixel content"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="int8" desc="The pixel content"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="int16" desc="The pixel content"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="int32" desc="The pixel content"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="int64" desc="The pixel content"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="float32" desc="The pixel content"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="float64" desc="The pixel content"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="uint8" desc="The BLUE pixel content"/>
<element_type name="uint8" desc="The GREEN pixel content"/>
<element_type name="uint8" desc="The RED pixel content"/>
</big_data_array>
</item>
</any_of>
</item>
</struct>
</item>
</struct>
</item>
{
"class" : "Image",
"data" : {
"PixelSize" : {
"x" : 1,
"y" : 1,
"z" : 1
},
"Origin" : {
"x" : 0,
"y" : 0,
"z" : 0
},
"HandleZeroPixels" : "Default",
"Data" : {
"ImageType" : "RGB24",
"Width" : 2,
"Height" : 2,
"Pixels" : {
"numOfElems" : 4,
"elemSz" : 3,
"endian" : "neutral",
"elemTypes" : [ "uint8", "uint8", "uint8" ],
"data" : "AgEABQQDCAcGCwoJ"
}
}
}
}
Image.Calibration.CameraModel
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="CameraID" desc="Unique camera identifier">
<string/>
</item>
<item name="ImageWidth" desc="Image width for which the calibration is valid">
<int signed="true" width="32"/>
</item>
<item name="ImageHeight" desc="Image height for which the calibration is valid">
<int signed="true" width="32"/>
</item>
<item name="FocalDistance" desc="Distance from the camera to the plane of best image sharpness">
<float width="64"/>
</item>
<item name="FocalDistanceUnit" desc="Focus distance unit (Default is mm)">
<string/>
</item>
<item name="IntrinsicK">
<array>
<item>
<array>
<item>
<float width="64"/>
</item>
</array>
</item>
</array>
</item>
<item name="WorldToSensorDistortion">
<array>
<item>
<array>
<item>
<float width="64"/>
</item>
</array>
</item>
</array>
</item>
<item name="SensorToWorldDistortion">
<array>
<item>
<array>
<item>
<float width="64"/>
</item>
</array>
</item>
</array>
</item>
<item name="WorldToView">
<array>
<item>
<array>
<item>
<float width="64"/>
</item>
</array>
</item>
</array>
</item>
</struct>
</item>
{
"class" : "Image.Calibration.CameraModel",
"data" : {
"CameraID" : "",
"ImageWidth" : 0,
"ImageHeight" : 0,
"FocalDistance" : 0,
"FocalDistanceUnit" : "",
"IntrinsicK" : [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ],
"WorldToSensorDistortion" : [ [ 0 ], [ 0 ], [ 0 ], [ 0 ], [ 0 ] ],
"SensorToWorldDistortion" : [ [ 0 ], [ 0 ], [ 0 ], [ 0 ], [ 0 ] ],
"WorldToView" : [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ]
}
}
Image.Fixture
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="PointsNames">
<array>
<item>
<string/>
</item>
</array>
</item>
<item name="Points">
<array>
<item>
<struct>
<item name="x">
<float width="64"/>
</item>
<item name="y">
<float width="64"/>
</item>
</struct>
</item>
</array>
</item>
<item name="ShapesNames">
<array>
<item>
<string/>
</item>
</array>
</item>
<item name="Shapes">
<array>
<item>
<polymorphic/>
</item>
</array>
</item>
<item name="CompositeShapesNames">
<array>
<item>
<string/>
</item>
</array>
</item>
<item name="CompositeShapes">
<array>
<item>
<polymorphic/>
</item>
</array>
</item>
<item name="AnglesNames">
<array>
<item>
<string/>
</item>
</array>
</item>
<item name="Angles">
<array>
<item>
<float width="64"/>
</item>
</array>
</item>
<item name="PosesNames">
<array>
<item>
<string/>
</item>
</array>
</item>
<item name="Poses">
<array>
<item>
<polymorphic/>
</item>
</array>
</item>
<item name="TeachPoseSet">
<bool/>
</item>
<item name="TransformSet">
<bool/>
</item>
<item name="TeachToMatch">
<polymorphic/>
</item>
<item name="TeachToModel">
<polymorphic/>
</item>
</struct>
</item>
{
"class" : "Image.Fixture",
"data" : {
"PointsNames" : [ "thePoint_0", "thePoint_1" ],
"Points" : [ {
"x" : 50,
"y" : 1000
}, {
"x" : 51,
"y" : 1001
} ],
"ShapesNames" : [ "theShape_0", "theShape_1" ],
"Shapes" : [ "Shape.Circle", "Shape.Line" ],
"CompositeShapesNames" : [ "theCompositeShape_0", "theCompositeShape_1" ],
"CompositeShapes" : [ "Shape.Composite", "Shape.Composite" ],
"AnglesNames" : [ "theAngle_0", "theAngle_1" ],
"Angles" : [ 1.1, 1.2 ],
"PosesNames" : [ "thePose_0", "thePose_1" ],
"Pose" : [ "Transform2D", "Transform2D" ],
"TeachPoseSet" : "true",
"TransformSet" : "true",
"TeachToMatch" : "Transform2D",
"TeachToModel" : "Transform2D"
}
}
Image.Fixture3D
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="PointsNames">
<array>
<item>
<string/>
</item>
</array>
</item>
<item name="Points">
<array>
<item>
<struct>
<item name="x">
<float width="64"/>
</item>
<item name="y">
<float width="64"/>
</item>
<item name="z">
<float width="64"/>
</item>
</struct>
</item>
</array>
</item>
<item name="ShapesNames">
<array>
<item>
<string/>
</item>
</array>
</item>
<item name="Shapes">
<array>
<item>
<polymorphic/>
</item>
</array>
</item>
<item name="PosesNames">
<array>
<item>
<string/>
</item>
</array>
</item>
<item name="Poses">
<array>
<item>
<polymorphic/>
</item>
</array>
</item>
<item name="TeachPoseSet">
<bool/>
</item>
<item name="TransformSet">
<bool/>
</item>
<item name="TeachToMatch">
<polymorphic/>
</item>
<item name="TeachToModel">
<polymorphic/>
</item>
</struct>
</item>
{
"class" : "Image.Fixture3D",
"data" : {
"PointsNames" : [ "thePoint_0", "thePoint_1" ],
"Points" : [ {
"x" : 50,
"y" : 1000
}, {
"x" : 51,
"y" : 1001
} ],
"ShapesNames" : [ "theShape_0", "theShape_1" ],
"Shapes" : [ "Shape.Circle", "Shape.Line" ],
"PosesNames" : [ "thePose_0", "thePose_1" ],
"Pose" : [ "Transform3D", "Transform3D" ],
"TeachPoseSet" : "true",
"TransformSet" : "true",
"TeachToMatch" : "Transform3D",
"TeachToModel" : "Transform3D"
}
}
Image.Matching.EdgeMatcher
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Version">
<int signed="true" width="32"/>
</item>
<item name="Params">
<struct>
<item name="EdgeThreshold">
<struct>
<item name="x">
<float width="64"/>
</item>
<item name="y">
<float width="64"/>
</item>
</struct>
</item>
<item name="ProcessingUnit">
<int signed="true" width="32"/>
</item>
</struct>
</item>
<item name="TimeoutSeconds">
<float width="64"/>
</item>
<item name="Matcher">
<string/>
</item>
</struct>
</item>
{
"class" : "Image.Matching.EdgeMatcher",
"data" : {
"Params" : {
"Version" : 2,
"EdgeThreshold" : {
"x" : 50,
"y" : 1000
},
"ProcessingUnit" : 1
},
"TimeoutSeconds" : 5,
"Matcher" : "aa"
}
}
Image.Matching.EdgeMatcher3D
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Version">
<int signed="true" width="32"/>
</item>
<item name="Params">
<struct>
<item name="EdgeThreshold">
<struct>
<item name="x">
<float width="64"/>
</item>
<item name="y">
<float width="64"/>
</item>
</struct>
</item>
<item name="ProcessingUnit">
<int signed="true" width="32"/>
</item>
</struct>
</item>
<item name="TimeoutSeconds">
<float width="64"/>
</item>
<item name="ReferencePlaneSet">
<bool/>
</item>
<item name="Matcher">
<string/>
</item>
</struct>
</item>
{
"class" : "Image.Matching.EdgeMatcher3D",
"data" : {
"Version" : 2,
"Params" : {
"EdgeThreshold" : {
"x" : 50,
"y" : 1000
},
"ProcessingUnit" : 1
},
"TimeoutSeconds" : 5,
"ReferencePlaneSet" : true,
"Matcher" : "aa"
}
}
Image.Matching.PointMatcher
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Version">
<int signed="true" width="32"/>
</item>
<item name="Matcher">
<string/>
</item>
</struct>
</item>
{
"class" : "Image.Matching.PointMatcher",
"data" : {
"Version" : 2,
"Matcher" : "aa"
}
}
Image.PixelRegion
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="segments" desc="Structs for individual segments of a run-length coded region">
<big_data_array>
<element_type name="int32" desc="y: Image row of the segment"/>
<element_type name="int32" desc="xStart: x-coordinate of first included pixel"/>
<element_type name="int32" desc="xStop: x-coordinate of last included pixel"/>
</big_data_array>
</item>
</struct>
</item>
{
"class" : "Image.PixelRegion",
"data" : {
"segments" : {
"numOfElems" : 2,
"elemSz" : 12,
"endian" : "little",
"elemTypes" : [ "int32", "int32", "int32" ],
"data" : "AQAAAAIAAAADAAAABAAAAAUAAAAGAAAA"
}
}
}
MachineLearning.DataSet
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Revision">
<int signed="true" width="32"/>
</item>
<item name="Width">
<int signed="true" width="32"/>
</item>
<item name="Height">
<int signed="true" width="32"/>
</item>
<item name="LabelType">
<any_of>
<item>
<string value="Classification"/>
</item>
<item>
<string value="Regression"/>
</item>
</any_of>
</item>
<item name="WeightsExist">
<bool/>
</item>
<item name="Samples">
<big_data_array>
<element_type name="float32"/>
</big_data_array>
</item>
<item name="Labels">
<any_of>
<item>
<big_data_array>
<element_type name="float32"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="int32"/>
</big_data_array>
</item>
</any_of>
</item>
<item name="Weights">
<big_data_array>
<element_type name="float32"/>
</big_data_array>
</item>
</struct>
</item>
{
"class" : "MachineLearning.DataSet",
"data" : {
"Revision" : 0,
"Width" : 0,
"Height" : 0,
"LabelType" : "Classification",
"WeightsExist" : false,
"Samples" : {
"numOfElems" : 0,
"elemSz" : 4,
"endian" : "little",
"elemTypes" : [ "float32" ],
"data" : ""
},
"Labels" : {
"numOfElems" : 0,
"elemSz" : 4,
"endian" : "little",
"elemTypes" : [ "int32" ],
"data" : ""
},
"Weights" : {
"numOfElems" : 0,
"elemSz" : 4,
"endian" : "little",
"elemTypes" : [ "float32" ],
"data" : ""
}
}
}
Matrix
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Rows" desc="Matrix height (in number of elements)">
<int signed="true" width="32"/>
</item>
<item name="Columns" desc="Matrix width (in number of elements)">
<int signed="true" width="32"/>
</item>
<item name="Elements" desc="Matrix elements in row-major storage order">
<big_data_array>
<element_type name="float64" desc="Single matrix element"/>
</big_data_array>
</item>
</struct>
</item>
{
"class" : "Matrix",
"data" : {
"Rows" : 2,
"Columns" : 2,
"Elements" : {
"numOfElems" : 4,
"elemSz" : 8,
"endian" : "little",
"elemTypes" : [ "float64" ],
"data" : "kiRJkiRJwj+SJEmSJEnSP9u2bdu2bds/kiRJkiRJ4j8="
}
}
}
Mesh
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Indices" desc="List of triangle indices">
<big_data_array>
<element_type name="uint32" desc="Vertex index"/>
</big_data_array>
</item>
<item name="Vertices" desc="Vertex position coordinates">
<big_data_array>
<element_type name="float32" desc="X coordinate"/>
<element_type name="float32" desc="Y coordinate"/>
<element_type name="float32" desc="Z coordinate"/>
</big_data_array>
</item>
<item name="Normals" desc="Vertex normal vectors">
<big_data_array>
<element_type name="float32" desc="X coordinate"/>
<element_type name="float32" desc="Y coordinate"/>
<element_type name="float32" desc="Z coordinate"/>
</big_data_array>
</item>
<item name="Colors" desc="Vertex color vectors">
<big_data_array>
<element_type name="uint8" desc="Red"/>
<element_type name="uint8" desc="Green"/>
<element_type name="uint8" desc="Blue"/>
<element_type name="uint8" desc="Alpha"/>
</big_data_array>
</item>
<item name="Intensities" desc="Vertex intensities">
<big_data_array>
<element_type name="float32" desc="Intensity"/>
</big_data_array>
</item>
<item name="TexCoords" desc="Vertex texture coordinates">
<big_data_array>
<element_type name="float32" desc="S coordinate"/>
<element_type name="float32" desc="T coordinate"/>
</big_data_array>
</item>
</struct>
</item>
{
"class" : "Mesh",
"data" : {
"Indices" : {
"numOfElems" : 6,
"elemSz" : 4,
"endian" : "little",
"elemTypes" : [ "uint32" ],
"data" : "AAAAAAEAAAACAAAAAQAAAAIAAAADAAAA"
},
"Vertices" : {
"numOfElems" : 4,
"elemSz" : 12,
"endian" : "little",
"elemTypes" : [ "float32", "float32", "float32" ],
"data" : "AAAAAAAAAAAAAAAAAAAAAAAAgD8AAAAAAACAPwAAAAAAAAAAAACAPwAAgD8AAAAA"
},
"Normals" : {
"numOfElems" : 4,
"elemSz" : 12,
"endian" : "little",
"elemTypes" : [ "float32", "float32", "float32" ],
"data" : "AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/"
},
"Colors" : {
"numOfElems" : 4,
"elemSz" : 4,
"endian" : "neutral",
"elemTypes" : [ "uint8", "uint8", "uint8", "uint8" ],
"data" : "/wAA////AP///wD/AP8A/w=="
},
"Intensities" : {
"numOfElems" : 4,
"elemSz" : 4,
"endian" : "little",
"elemTypes" : [ "float32" ],
"data" : "zczMPc3MTD6amZk+zczMPg=="
},
"TexCoords" : {
"numOfElems" : 4,
"elemSz" : 8,
"endian" : "little",
"elemTypes" : [ "float32", "float32" ],
"data" : "AAAAAAAAAAAAAAAAAACAPwAAgD8AAAAAAAAAAAAAgD8="
}
}
}
Parameters.Node
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="type">
<any_of>
<item>
<string value="SInt"/>
</item>
<item>
<string value="Int"/>
</item>
<item>
<string value="DInt"/>
</item>
<item>
<string value="LInt"/>
</item>
<item>
<string value="USInt"/>
</item>
<item>
<string value="UInt"/>
</item>
<item>
<string value="UDInt"/>
</item>
<item>
<string value="ULInt"/>
</item>
<item>
<string value="Real"/>
</item>
<item>
<string value="LReal"/>
</item>
<item>
<string value="Bool"/>
</item>
<item>
<string value="String"/>
</item>
<item>
<string value="Array"/>
</item>
<item>
<string value="Struct"/>
</item>
</any_of>
</item>
<item name="value">
<data_format_ref name="Parameters.Node.Variant"/>
</item>
</struct>
</item>
{
"class" : "Parameters.Node",
"data" : {
"type" : "Int",
"value" : 0
}
}
Parameters.Node.Array
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="type">
<string/>
</item>
<item name="value">
<array>
<item>
<data_format_ref name="Parameters.Node.Variant"/>
</item>
</array>
</item>
</struct>
</item>
{
"type" : "Int",
"value" : [ 1, 1, 3 ]
}
Parameters.Node.Struct
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<array>
<item>
<struct>
<item name="name">
<string/>
</item>
<item name="type">
<any_of>
<item>
<string value="SInt"/>
</item>
<item>
<string value="Int"/>
</item>
<item>
<string value="DInt"/>
</item>
<item>
<string value="LInt"/>
</item>
<item>
<string value="USInt"/>
</item>
<item>
<string value="UInt"/>
</item>
<item>
<string value="UDInt"/>
</item>
<item>
<string value="ULInt"/>
</item>
<item>
<string value="Real"/>
</item>
<item>
<string value="LReal"/>
</item>
<item>
<string value="Bool"/>
</item>
<item>
<string value="String"/>
</item>
<item>
<string value="Array"/>
</item>
<item>
<string value="Struct"/>
</item>
</any_of>
</item>
<item name="value">
<data_format_ref name="Parameters.Node.Variant"/>
</item>
</struct>
</item>
</array>
</item>
[ {
"name" : "member1",
"type" : "Int",
"value" : 1
} ]
Parameters.Node.Variant
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<any_of>
<item>
<int signed="true" width="64"/>
</item>
<item>
<int signed="false" width="64"/>
</item>
<item>
<float width="64"/>
</item>
<item>
<bool/>
</item>
<item>
<string/>
</item>
<item>
<data_format_ref name="Parameters.Node.Struct"/>
</item>
<item>
<data_format_ref name="Parameters.Node.Array"/>
</item>
</any_of>
</item>
1
Point
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<polymorphic>
<data_format_ref name="Point2D"/>
<data_format_ref name="Point3D"/>
</polymorphic>
</item>
Point2D
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="x" desc="X coordinate">
<float width="64"/>
</item>
<item name="y" desc="Y coordinate">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "Point2D",
"data" : {
"x" : 1.0,
"y" : 2.0
}
}
Point3D
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="x" desc="X coordinate">
<float width="64"/>
</item>
<item name="y" desc="Y coordinate">
<float width="64"/>
</item>
<item name="z" desc="Z coordinate">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "Point3D",
"data" : {
"x" : 1.0,
"y" : 2.0,
"z" : 3.0
}
}
Point3D_32
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="x" desc="X coordinate">
<float width="32"/>
</item>
<item name="y" desc="Y coordinate">
<float width="32"/>
</item>
<item name="z" desc="Z coordinate">
<float width="32"/>
</item>
</struct>
</item>
{
"class" : "Point3D_32",
"data" : {
"x" : 1.0,
"y" : 2.0,
"z" : 3.0
}
}
PointCloud
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<polymorphic>
<data_format_ref name="PointCloud.XYZI"/>
</polymorphic>
</item>
PointCloud.XYZI
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Width" desc="Width of the data matrix if organized, total size if not">
<int signed="true" width="32"/>
</item>
<item name="Height" desc="Height of the data matrix if organized, 1 if not">
<int signed="true" width="32"/>
</item>
<item name="IsDense" desc="True if no points are invalid">
<bool/>
</item>
<item name="ColorMode" desc="Point cloud color mode">
<any_of>
<item>
<string value="INTENSITY"/>
</item>
<item>
<string value="RGBA"/>
</item>
</any_of>
</item>
<item name="Number" desc="Point cloud identifier (e.g. object ID or sequence number)">
<int signed="false" width="32"/>
</item>
<item name="TimeStamp" desc="Time stamp in microseconds">
<int signed="false" width="32"/>
</item>
<item name="SensorIDs" desc="ID(s) of the sensor(s)">
<array>
<item>
<int signed="false" width="32"/>
</item>
</array>
</item>
<item name="SensorPositions" desc="Position of the sensor(s) (x, y, z in mm)">
<array>
<item>
<data_format_ref name="Point3D_32"/>
</item>
</array>
</item>
<item name="SensorOrientations" desc="Orientation of the sensor(s) (yaw, pitch, roll in radians)">
<array>
<item>
<data_format_ref name="Point3D_32"/>
</item>
</array>
</item>
<item name="Points" desc="Each point has a size of 16 bytes, the format of the last 4 bytes depends on the ColorMode">
<any_of>
<item>
<big_data_array>
<element_type name="float32" desc="X coordinate"/>
<element_type name="float32" desc="Y coordinate"/>
<element_type name="float32" desc="Z coordinate"/>
<element_type name="float32" desc="Intensity value"/>
</big_data_array>
</item>
<item>
<big_data_array>
<element_type name="float32" desc="X coordinate"/>
<element_type name="float32" desc="Y coordinate"/>
<element_type name="float32" desc="Z coordinate"/>
<element_type name="uint8" desc="Red"/>
<element_type name="uint8" desc="Green"/>
<element_type name="uint8" desc="Blue"/>
<element_type name="uint8" desc="Alpha"/>
</big_data_array>
</item>
</any_of>
</item>
</struct>
</item>
{
"class" : " PointCloud.XYZI",
"data" : {
"Width" : 2,
"Height" : 1,
"IsDense" : true,
"ColorMode" : "INTENSITY",
"Number" : 42,
"TimeStamp" : 2880154539,
"SensorIDs" : [ 1, 2 ],
"SensorPositions" : [ {
"x" : 1,
"y" : 2,
"z" : 3
}, {
"x" : 7,
"y" : 8,
"z" : 9
} ],
"SensorOrientations" : [ {
"x" : 4,
"y" : 5,
"z" : 6
}, {
"x" : 10,
"y" : 11,
"z" : 12
} ],
"Points" : {
"numOfElems" : 2,
"elemSz" : 16,
"endian" : "little",
"elemTypes" : [ "float32", "float32", "float32", "float32" ],
"data" : "AACAPwAAAEAAAEBAAACAPwAAgEAAAKBAAADAQAAAgD8="
}
}
}
Profile
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="IsClosed">
<bool/>
</item>
<item name="UseValidFlags">
<bool/>
</item>
<item name="Values">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="ValidFlags">
<array>
<item>
<int signed="false" width="8"/>
</item>
</array>
</item>
<item name="StartImplicit1D">
<float width="64"/>
</item>
<item name="DeltaImplicit1D">
<float width="64"/>
</item>
<item name="CoordinatesExplicit1D">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="StartImplicit2D">
<data_format_ref name="Point2D"/>
</item>
<item name="DeltaImplicit2D">
<data_format_ref name="Point2D"/>
</item>
<item name="CoordinatesExplicit2D">
<array>
<item>
<data_format_ref name="Point2D"/>
</item>
</array>
</item>
<item name="CoordinateType">
<any_of>
<item>
<string value="IMPLICIT_1D"/>
</item>
<item>
<string value="EXPLICIT_1D"/>
</item>
<item>
<string value="IMPLICIT_2D"/>
</item>
<item>
<string value="EXPLICIT_2D"/>
</item>
</any_of>
</item>
</struct>
</item>
{
"class" : "Profile",
"data" : {
"IsClosed" : false,
"UseValidFlags" : true,
"Values" : [ 2, 2, 2 ],
"ValidFlags" : [ 1, 1, 1 ],
"StartImplicit1D" : 0,
"DeltaImplicit1D" : 1,
"CoordinatesExplicit1D" : [ 0, 1, 2 ],
"StartImplicit2D" : {
"x" : 0,
"y" : 0
},
"DeltaImplicit2D" : {
"x" : 1,
"y" : 0
},
"CoordinatesExplicit2D" : [ ],
"CoordinateType" : "EXPLICIT_1D"
}
}
Profile.Curve
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<polymorphic>
<data_format_ref name="Profile.Curve.Polynomial"/>
<data_format_ref name="Profile.Curve.Exponential"/>
<data_format_ref name="Profile.Curve.Gaussian"/>
</polymorphic>
</item>
{
"class" : "Profile.Curve.Polynomial",
"data" : {
"coefficients" : [ 1.0, 2.0, 3.0 ]
}
}
Profile.Curve.Exponential
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Coefficients">
<array length="3">
<item>
<float width="64"/>
</item>
</array>
</item>
</struct>
</item>
{
"class" : "Profile.Curve.Exponential",
"data" : {
"Coefficients" : [ 1.0, 2.0, 3.0 ]
}
}
Profile.Curve.Gaussian
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Coefficients">
<array length="4">
<item>
<float width="64"/>
</item>
</array>
</item>
</struct>
</item>
{
"class" : "Profile.Curve.Gaussian",
"data" : {
"Coefficients" : [ 1.0, 2.0, 3.0, 4.0 ]
}
}
Profile.Curve.Polynomial
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Coefficients">
<array>
<item>
<float width="64"/>
</item>
</array>
</item>
</struct>
</item>
{
"class" : "Profile.Curve.Polynomial",
"data" : {
"Coefficients" : [ 1.0, 2.0, 3.0 ]
}
}
Profile.Log
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="RecentValuesEnabled">
<bool/>
</item>
<item name="Values">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="Coordinates">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="Count">
<int signed="false" width="64"/>
</item>
<item name="M2">
<float width="64"/>
</item>
<item name="Mean">
<float width="64"/>
</item>
<item name="Min">
<float width="32"/>
</item>
<item name="MinCoord">
<float width="32"/>
</item>
<item name="Max">
<float width="32"/>
</item>
<item name="MaxCoord">
<float width="32"/>
</item>
<item name="HistogramEnabled">
<bool/>
</item>
<item name="Histogram">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="HistogramMinValue">
<float width="32"/>
</item>
<item name="HistogramDelta">
<float width="32"/>
</item>
<item name="RecentBack">
<int signed="false" width="unspecified"/>
</item>
<item name="HistoricStatisticsEnabled">
<bool/>
</item>
<item name="HistoricValueBuffer">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="HistoricCoordBuffer">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="HistoricCoordinates">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="HistoricMeanValues">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="HistoricStdDevValues">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="HistoricMaxValues">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="HistoricMinValues">
<array>
<item>
<float width="32"/>
</item>
</array>
</item>
<item name="HistoricQuanta">
<int signed="false" width="64"/>
</item>
<item name="PeriodCount">
<int signed="false" width="32"/>
</item>
</struct>
</item>
{
"class" : "Profile.Log",
"data" : {
"RecentValuesEnabled" : false,
"Values" : [ ],
"Coordinates" : [ ],
"Min" : -3.200000047,
"MinCoord" : 3.140000104,
"Max" : 1.200000047,
"MaxCoord" : 0,
"Mean" : -0.5666666626930237,
"M2" : 10.806667106946314,
"Count" : 3,
"HistogramEnabled" : false,
"Histogram" : [ ],
"HistogramMinValue" : 0,
"HistogramDelta" : 0,
"RecentBack" : 0,
"HistoricStatisticsEnabled" : true,
"HistoricValueBuffer" : [ 0.300000011 ],
"HistoricCoordBuffer" : [ 0 ],
"HistoricCoordinates" : [ 1.570000052 ],
"HistoricMeanValues" : [ -1 ],
"HistoricStdDevValues" : [ 2.200000047 ],
"HistoricMaxValues" : [ 1.200000047 ],
"HistoricMinValues" : [ -3.200000047 ],
"HistoricQuanta" : 2,
"PeriodCount" : 4
}
}
SensorData
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Encoder" desc="Encoder data. May be optional and filled with default values when not available">
<data_format_ref name="EncoderData"/>
</item>
<item name="Timestamp" desc="Application specific time stamp in microseconds">
<int signed="false" width="64"/>
</item>
<item name="FrameNo" desc="Capture driver specific frame number">
<int signed="false" width="32"/>
</item>
<item name="Ident" desc="Application specific ID where the corresponding image can be assigned to. Is -1 when not used or invalid.">
<int signed="true" width="32"/>
</item>
<item name="Origin" desc="Dot separated list of image providers where the image originated from">
<string/>
</item>
<item name="Name" desc="Name of the corresponding data object">
<string/>
</item>
<item name="MetaData">
<polymorphic can_be_null="true">
<data_format_ref name="Container"/>
</polymorphic>
</item>
</struct>
</item>
{
"class" : "SensorData",
"data" : {
"Encoder" : {
"Position" : 0,
"Speed" : 0,
"SystemIncrement" : 0,
"TimestampUTC" : 0,
"TimestampUS" : 0,
"xValue" : 0
},
"Timestamp" : 0,
"FrameNo" : 0,
"Ident" : -1,
"Origin" : "",
"Name" : ""
}
}
Shape
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<polymorphic>
<data_format_ref name="Shape.Arc"/>
<data_format_ref name="Shape.Circle"/>
<data_format_ref name="Shape.Composite"/>
<data_format_ref name="Shape.Ellipse"/>
<data_format_ref name="Shape.Line"/>
<data_format_ref name="Shape.LineSegment"/>
<data_format_ref name="Shape.PolyLine"/>
<data_format_ref name="Shape.Rectangle"/>
<data_format_ref name="Shape.Sector"/>
</polymorphic>
</item>
{
"class" : "Shape.Circle",
"data" : {
"cx" : 0.0,
"cy" : 1.0,
"radius" : 2.0
}
}
Shape.Arc
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="cx" desc="Center point X coordinate">
<float width="64"/>
</item>
<item name="cy" desc="Center point Y coordinate">
<float width="64"/>
</item>
<item name="radius" desc="Radius">
<float width="64"/>
</item>
<item name="angle" desc="Initial angle of the arc in radians">
<float width="64"/>
</item>
<item name="deltaAngle" desc="Angular size of the arc in radians">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "Shape.Arc",
"data" : {
"cx" : 10.0,
"cy" : 10.0,
"radius" : 1.0,
"angle" : 0.0,
"deltaAngle" : 3.1415927
}
}
Shape.Circle
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="cx" desc="Center point X coordinate">
<float width="64"/>
</item>
<item name="cy" desc="Center point Y coordinate">
<float width="64"/>
</item>
<item name="radius" desc="Radius">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "Shape.Circle",
"data" : {
"cx" : 0.0,
"cy" : 1.0,
"radius" : 2.0
}
}
Shape.Composite
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="shapes">
<array>
<item>
<struct>
<item name="isPositive">
<bool/>
</item>
<item name="shape">
<data_format_ref name="Shape"/>
</item>
</struct>
</item>
</array>
</item>
</struct>
</item>
{
"class" : "Shape.Composite",
"data" : {
"shapes" : [ {
"isPositive" : true,
"shape" : {
"class" : "Shape.Circle",
"data" : {
"cx" : 1,
"cy" : 2,
"radius" : 3
}
}
}, {
"isPositive" : false,
"shape" : {
"class" : "Shape.Circle",
"data" : {
"cx" : 2,
"cy" : 3,
"radius" : 4
}
}
} ]
}
}
Shape.Ellipse
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="cx" desc="Center point X coordinate">
<float width="64"/>
</item>
<item name="cy" desc="Center point Y coordinate">
<float width="64"/>
</item>
<item name="radiusX" desc="Radius in X direction">
<float width="64"/>
</item>
<item name="radiusY" desc="Radius in Y direction">
<float width="64"/>
</item>
<item name="orientationRad" desc="Orientation angle in radians">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "Shape.Ellipse",
"data" : {
"cx" : 1.0,
"cy" : 2.0,
"radiusX" : 3.0,
"radiusY" : 4.0,
"orientationRad" : 0.0
}
}
Shape.Line
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="x1" desc="Line starting point X coordinate">
<float width="64"/>
</item>
<item name="y1" desc="Line starting point Y coordinate">
<float width="64"/>
</item>
<item name="xDir" desc="Direction vector X coordinate">
<float width="64"/>
</item>
<item name="yDir" desc="Direction vector Y coordinate">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "Shape.Line",
"data" : {
"x1" : 1.0,
"y1" : 2.0,
"xDir" : 1.0,
"yDir" : 1.0
}
}
Shape.LineSegment
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="x1" desc="Line starting point X coordinate">
<float width="64"/>
</item>
<item name="y1" desc="Line starting point Y coordinate">
<float width="64"/>
</item>
<item name="x2" desc="Line ending point X coordinate">
<float width="64"/>
</item>
<item name="y2" desc="Line ending point X coordinate">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "Shape.LineSegment",
"data" : {
"x1" : 1.0,
"y1" : 2.0,
"x2" : 2.0,
"y2" : 3.0
}
}
Shape.PolyLine
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="points">
<array>
<item>
<data_format_ref name="Point2D"/>
</item>
</array>
</item>
<item name="isClosed">
<bool/>
</item>
</struct>
</item>
{
"class" : "Shape.PolyLine",
"data" : {
"points" : [ {
"x" : 1.0,
"y" : 2.0
}, {
"x" : 3.0,
"y" : 4.0
} ],
"isClosed" : false
}
}
Shape.Rectangle
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="cx" desc="Center point X coordinate">
<float width="64"/>
</item>
<item name="cy" desc="Center point Y coordinate">
<float width="64"/>
</item>
<item name="width" desc="Rectangle width">
<float width="64"/>
</item>
<item name="height" desc="Rectangle height">
<float width="64"/>
</item>
<item name="orientationRad" desc="Orientation angle in radians">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "Shape.Rectangle",
"data" : {
"cx" : 1.0,
"cy" : 2.0,
"width" : 3.0,
"height" : 4.0,
"orientationRad" : 0.0
}
}
Shape.Sector
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="cx" desc="Center point X coordinate">
<float width="64"/>
</item>
<item name="cy" desc="Center point Y coordinate">
<float width="64"/>
</item>
<item name="innerRadius" desc="Inner radius of the sector">
<float width="64"/>
</item>
<item name="outerRadius" desc="Outer radius of the sector">
<float width="64"/>
</item>
<item name="angle" desc="Initial angle of the arc in radians">
<float width="64"/>
</item>
<item name="deltaAngle" desc="Angular size of the arc in radians">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "Shape.Sector",
"data" : {
"cx" : 10.0,
"cy" : 10.0,
"innerRadius" : 1.0,
"outerRadius" : 2.0,
"angle" : 0.0,
"deltaAngle" : 3.1415927
}
}
Shape3D
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<polymorphic>
<data_format_ref name="Shape3D.Box"/>
<data_format_ref name="Shape3D.Circle"/>
<data_format_ref name="Shape3D.Cone"/>
<data_format_ref name="Shape3D.Cylinder"/>
<data_format_ref name="Shape3D.Ellipse"/>
<data_format_ref name="Shape3D.EllipticCylinder"/>
<data_format_ref name="Shape3D.Line"/>
<data_format_ref name="Shape3D.LineSegment"/>
<data_format_ref name="Shape3D.Plane"/>
<data_format_ref name="Shape3D.Polygon"/>
<data_format_ref name="Shape3D.Polyline"/>
<data_format_ref name="Shape3D.Rectangle"/>
<data_format_ref name="Shape3D.Sphere"/>
</polymorphic>
</item>
{
"class" : "Shape3D.Box",
"data" : {
"sizeX" : 10,
"sizeY" : 11,
"sizeZ" : 12,
"pose" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
}
}
}
Shape3D.Box
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="sizeX" desc="Total extent of the box along its local x-direction">
<float width="64"/>
</item>
<item name="sizeY" desc="Total extent of the box along its local y-direction">
<float width="64"/>
</item>
<item name="sizeZ" desc="Total extent of the box along its local z-direction">
<float width="64"/>
</item>
<item name="pose" desc="Position and orientation of the shape">
<data_format_ref name="Transform3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.Box",
"data" : {
"sizeX" : 10,
"sizeY" : 11,
"sizeZ" : 12,
"pose" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
}
}
}
Shape3D.Circle
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="radius" desc="Radius of the circle">
<float width="64"/>
</item>
<item name="pose" desc="Position and orientation of the shape">
<data_format_ref name="Transform3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.Circle",
"data" : {
"radius" : 10,
"pose" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
}
}
}
Shape3D.Cone
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="radius" desc="Radius of the cone">
<float width="64"/>
</item>
<item name="height" desc="Height of the cone along its local z-direction">
<float width="64"/>
</item>
<item name="pose" desc="Position and orientation of the shape">
<data_format_ref name="Transform3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.Cone",
"data" : {
"radius" : 10,
"height" : 4,
"pose" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
}
}
}
Shape3D.Cylinder
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="radius" desc="Radius of the cylinder">
<float width="64"/>
</item>
<item name="height" desc="Height of the cylinder along its local z-direction">
<float width="64"/>
</item>
<item name="pose" desc="Position and orientation of the shape">
<data_format_ref name="Transform3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.Cylinder",
"data" : {
"radius" : 10,
"height" : 4,
"pose" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
}
}
}
Shape3D.Ellipse
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="radiusX" desc="Radius of the ellipse in the local x-direction">
<float width="64"/>
</item>
<item name="radiusY" desc="Radius of the ellipse in the local y-direction">
<float width="64"/>
</item>
<item name="pose" desc="Position and orientation of the shape">
<data_format_ref name="Transform3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.Ellipse",
"data" : {
"radiusX" : 10,
"radiusY" : 5,
"pose" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
}
}
}
Shape3D.EllipticCylinder
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="radiusX" desc="Radius of the elliptic cylinder in the local x-direction">
<float width="64"/>
</item>
<item name="radiusY" desc="Radius of the elliptic cylinder in the local y-direction">
<float width="64"/>
</item>
<item name="height" desc="Height of the elliptic cylinder in the local z-direction">
<float width="64"/>
</item>
<item name="pose" desc="Position and orientation of the shape">
<data_format_ref name="Transform3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.EllipticCylinder",
"data" : {
"radiusX" : 10,
"radiusY" : 5,
"height" : 7,
"pose" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
}
}
}
Shape3D.Line
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="point" desc="A point on the line">
<data_format_ref name="Point3D"/>
</item>
<item name="direction" desc="The direction of the line, unit vector">
<data_format_ref name="Point3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.Line",
"data" : {
"point" : {
"x" : 11,
"y" : 12,
"z" : 13
},
"direction" : {
"x" : 0,
"y" : 1,
"z" : 0
}
}
}
Shape3D.LineSegment
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="point1" desc="The first end point of the line segment">
<data_format_ref name="Point3D"/>
</item>
<item name="point2" desc="The other end point of the line segment">
<data_format_ref name="Point3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.LineSegment",
"data" : {
"point1" : {
"x" : 11,
"y" : 12,
"z" : 13
},
"point2" : {
"x" : 10,
"y" : -2,
"z" : 0
}
}
}
Shape3D.Plane
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="normal" desc="The plane normal">
<data_format_ref name="Point3D"/>
</item>
<item name="distance" desc="The distance from the origin to the plane">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.Plane",
"data" : {
"normal" : {
"x" : 11,
"y" : 12,
"z" : 13
},
"distance" : 5
}
}
Shape3D.Polygon
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="points">
<array>
<item>
<data_format_ref name="Point2D"/>
</item>
</array>
</item>
<item name="pose" desc="Position and orientation of the shape">
<data_format_ref name="Transform3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.Polygon",
"data" : {
"points" : [ {
"x" : 1.0,
"y" : 2.0
}, {
"x" : 4.0,
"y" : 5.0
} ],
"pose" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
}
}
}
Shape3D.Polyline
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="points">
<array>
<item>
<data_format_ref name="Point3D"/>
</item>
</array>
</item>
</struct>
</item>
{
"class" : "Shape3D.Polyline",
"data" : {
"points" : [ {
"x" : 1.0,
"y" : 2.0,
"z" : 3.0
}, {
"x" : 4.0,
"y" : 5.0,
"z" : 6.0
} ]
}
}
Shape3D.Rectangle
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="sizeX" desc="Total extent of the rectangle along its local x-direction">
<float width="64"/>
</item>
<item name="sizeY" desc="Total extent of the rectangle along its local y-direction">
<float width="64"/>
</item>
<item name="pose" desc="Position and orientation of the shape">
<data_format_ref name="Transform3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.Rectangle",
"data" : {
"sizeX" : 10,
"sizeY" : 4,
"pose" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
}
}
}
Shape3D.Sphere
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="radius" desc="Radius of the sphere">
<float width="64"/>
</item>
<item name="pose" desc="Position and orientation of the shape">
<data_format_ref name="Transform3D"/>
</item>
</struct>
</item>
{
"class" : "Shape3D.Sphere",
"data" : {
"radius" : 10,
"pose" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
}
}
}
Transform
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<polymorphic>
<data_format_ref name="Transform2D"/>
<data_format_ref name="Transform3D"/>
</polymorphic>
</item>
{
"class" : "Transform2D",
"data" : {
"Type" : "IDENTITY",
"Matrix" : [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]
}
}
Transform2D
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Type">
<any_of>
<item>
<string value="IDENTITY"/>
</item>
<item>
<string value="TRANSLATION"/>
</item>
<item>
<string value="RIGID"/>
</item>
<item>
<string value="SIMILARITY"/>
</item>
<item>
<string value="AFFINE"/>
</item>
<item>
<string value="HOMOGRAPHY"/>
</item>
</any_of>
</item>
<item name="Matrix">
<array>
<item>
<array>
<item>
<float width="64"/>
</item>
</array>
</item>
</array>
</item>
</struct>
</item>
{
"class" : "Transform2D",
"data" : {
"Type" : "IDENTITY",
"Matrix" : [ [ 1, 0, 0 ], [ 0, 1, 0 ], [ 0, 0, 1 ] ]
}
}
Transform3D
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Type">
<any_of>
<item>
<string value="IDENTITY"/>
</item>
<item>
<string value="TRANSLATION"/>
</item>
<item>
<string value="RIGID"/>
</item>
<item>
<string value="SIMILARITY"/>
</item>
<item>
<string value="AFFINE"/>
</item>
<item>
<string value="HOMOGRAPHY"/>
</item>
</any_of>
</item>
<item name="Matrix">
<array>
<item>
<array>
<item>
<float width="64"/>
</item>
</array>
</item>
</array>
</item>
</struct>
</item>
{
"class" : "Transform3D",
"data" : {
"Type" : "IDENTITY",
"Matrix" : [ [ 1, 0, 0, 0 ], [ 0, 1, 0, 0 ], [ 0, 0, 1, 0 ], [ 0, 0, 0, 1 ] ]
}
}
View.Camera
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Position">
<data_format_ref name="Point3D"/>
</item>
<item name="Target">
<data_format_ref name="Point3D"/>
</item>
<item name="Up">
<data_format_ref name="Point3D"/>
</item>
</struct>
</item>
{
"class" : "View.Camera",
"data" : {
"Position" : {
"x" : 0,
"y" : -1,
"z" : 2000
},
"Target" : {
"x" : 0,
"y" : 0,
"z" : 0
},
"Up" : {
"x" : 0,
"y" : 0,
"z" : 1
},
"PositionSet" : true,
"TargetSet" : true,
"UpSet" : true
}
}
View.ColorMap
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="ColorMapType">
<any_of>
<item>
<string value="LINEAR"/>
</item>
<item>
<string value="DISCRETE"/>
</item>
</any_of>
</item>
<item name="ColorStops">
<array>
<item>
<struct>
<item name="Value">
<float width="64"/>
</item>
<item name="R">
<int signed="false" width="8"/>
</item>
<item name="G">
<int signed="false" width="8"/>
</item>
<item name="B">
<int signed="false" width="8"/>
</item>
<item name="A">
<int signed="false" width="8"/>
</item>
</struct>
</item>
</array>
</item>
<item name="RangeStart">
<float width="64"/>
</item>
<item name="RangeStop">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "View.ColorMap",
"data" : {
"ColorMapType" : "LINEAR",
"ColorStops" : [ {
"Value" : 0.0,
"R" : 255,
"G" : 0,
"B" : 0,
"A" : 255
}, {
"Value" : 1.0,
"R" : 0,
"G" : 255,
"B" : 0,
"A" : 255
} ],
"Id" : 6235,
"RangeStart" : 0.0,
"RangeStop" : 1.0
}
}
View.GraphDecoration
View.GraphDecoration.ASPECTRATIO, View.GraphDecoration.GRAPHTYPE, View.GraphDecoration.RGBA
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="AxisColor">
<data_format_ref name="View.GraphDecoration.RGBA"/>
</item>
<item name="BackgroundColor">
<data_format_ref name="View.GraphDecoration.RGBA"/>
</item>
<item name="GraphColor">
<data_format_ref name="View.GraphDecoration.RGBA"/>
</item>
<item name="GridColor">
<data_format_ref name="View.GraphDecoration.RGBA"/>
</item>
<item name="LabelColor">
<data_format_ref name="View.GraphDecoration.RGBA"/>
</item>
<item name="GraphType">
<data_format_ref name="View.GraphDecoration.GRAPHTYPE"/>
</item>
<item name="AspectRatio">
<data_format_ref name="View.GraphDecoration.ASPECTRATIO"/>
</item>
<item name="AxisVisible">
<bool/>
</item>
<item name="BackgroundVisible">
<bool/>
</item>
<item name="GridVisible">
<bool/>
</item>
<item name="LabelsVisible">
<bool/>
</item>
<item name="TicksVisible">
<bool/>
</item>
<item name="UseIndexCoordinates">
<bool/>
</item>
<item name="UsePolarPlot">
<bool/>
</item>
<item name="DynamicSizing">
<bool/>
</item>
<item name="DrawSize">
<float width="32"/>
</item>
<item name="AxisWidth">
<float width="32"/>
</item>
<item name="LabelSize">
<float width="32"/>
</item>
<item name="TitleSize">
<float width="32"/>
</item>
<item name="LowerXBound">
<float width="32"/>
</item>
<item name="LowerYBound">
<float width="32"/>
</item>
<item name="UpperXBound">
<float width="32"/>
</item>
<item name="UpperYBound">
<float width="32"/>
</item>
<item name="XLabel">
<string/>
</item>
<item name="YLabel">
<string/>
</item>
<item name="Title">
<string/>
</item>
</struct>
</item>
{
"class" : "View.GraphDecoration",
"data" : {
"AxisColor" : {
"R" : 255,
"G" : 255,
"B" : 0,
"A" : 255
},
"BackgroundColor" : {
"R" : 255,
"G" : 0,
"B" : 255,
"A" : 255
},
"GraphColor" : {
"R" : 0,
"G" : 255,
"B" : 255,
"A" : 255
},
"GridColor" : {
"R" : 255,
"G" : 255,
"B" : 0,
"A" : 0
},
"LabelColor" : {
"R" : 0,
"G" : 255,
"B" : 0,
"A" : 255
},
"GraphType" : "DOT",
"AspectRatio" : "EQUAL",
"AxisVisible" : false,
"BackgroundVisible" : false,
"GridVisible" : false,
"LabelsVisible" : false,
"TicksVisible" : false,
"UseIndexCoordinates" : true,
"UsePolarPlot" : true,
"DynamicSizing" : true,
"DrawSize" : 5,
"AxisWidth" : 2.5,
"LabelSize" : 7,
"TitleSize" : 9,
"LowerXBound" : -100,
"LowerYBound" : -200,
"UpperXBound" : 100,
"UpperYBound" : 200,
"XLabel" : "x-axis",
"YLabel" : "y-axis",
"Title" : "Test Title"
}
}
View.GraphDecoration.ASPECTRATIO
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<any_of>
<item>
<string value="EQUAL"/>
</item>
<item>
<string value="SQUARE"/>
</item>
<item>
<string value="FIT"/>
</item>
</any_of>
</item>
View.GraphDecoration.GRAPHTYPE
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<any_of>
<item>
<string value="DOT"/>
</item>
<item>
<string value="LINE"/>
</item>
<item>
<string value="BAR"/>
</item>
</any_of>
</item>
View.GraphDecoration.RGBA
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="R" desc="Red component">
<int signed="false" width="8"/>
</item>
<item name="G" desc="Green component">
<int signed="false" width="8"/>
</item>
<item name="B" desc="Blue component">
<int signed="false" width="8"/>
</item>
<item name="A" desc="Alpha component">
<int signed="false" width="8"/>
</item>
</struct>
</item>
View.ImageDecoration
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="DataRange">
<data_format_ref name="View.ImageDecoration.DataRange"/>
</item>
<item name="ColorMap">
<int signed="true" width="32"/>
</item>
</struct>
</item>
{
"class" : "View.ImageDecoration",
"data" : {
"DataRange" : {
"Min" : 0,
"Max" : 255
},
"ColorMap" : 0
}
}
View.ImageDecoration.DataRange
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Min">
<float width="64"/>
</item>
<item name="Max">
<float width="64"/>
</item>
</struct>
</item>
View.MeshDecoration
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="SurfaceColor">
<struct>
<item name="R" desc="Red component">
<int signed="false" width="8"/>
</item>
<item name="G" desc="Green component">
<int signed="false" width="8"/>
</item>
<item name="B" desc="Blue component">
<int signed="false" width="8"/>
</item>
<item name="A" desc="Alpha component">
<int signed="false" width="8"/>
</item>
</struct>
</item>
<item name="VisibleFaces">
<data_format_ref name="View.MeshDecoration.VisibleFaces"/>
</item>
</struct>
</item>
{
"class" : "View.MeshDecoration",
"data" : {
"SurfaceColor" : {
"R" : 255,
"G" : 255,
"B" : 255,
"A" : 255
},
"VisibleFaces" : "FRONT_AND_BACK"
}
}
View.MeshDecoration.VisibleFaces
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<any_of>
<item>
<string value="FRONT"/>
</item>
<item>
<string value="BACK"/>
</item>
<item>
<string value="FRONT_AND_BACK"/>
</item>
<item>
<string value="NONE"/>
</item>
</any_of>
</item>
View.PixelRegionDecoration
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Color">
<data_format_ref name="View.PixelRegionDecoration.RGBA"/>
</item>
</struct>
</item>
{
"class" : "View.PixelRegionDecoration",
"data" : {
"Color" : {
"R" : 0,
"G" : 127,
"B" : 195,
"A" : 255
}
}
}
View.PixelRegionDecoration.RGBA
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="R" desc="Red component">
<int signed="false" width="8"/>
</item>
<item name="G" desc="Green component">
<int signed="false" width="8"/>
</item>
<item name="B" desc="Blue component">
<int signed="false" width="8"/>
</item>
<item name="A" desc="Alpha component">
<int signed="false" width="8"/>
</item>
</struct>
</item>
View.PointCloudDecoration
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="XMax">
<float width="64"/>
</item>
<item name="YMax">
<float width="64"/>
</item>
<item name="ZMax">
<float width="64"/>
</item>
<item name="IMax">
<float width="64"/>
</item>
<item name="XMin">
<float width="64"/>
</item>
<item name="YMin">
<float width="64"/>
</item>
<item name="ZMin">
<float width="64"/>
</item>
<item name="IMin">
<float width="64"/>
</item>
<item name="XRangeSet">
<bool/>
</item>
<item name="YRangeSet">
<bool/>
</item>
<item name="ZRangeSet">
<bool/>
</item>
<item name="IRangeSet">
<bool/>
</item>
<item name="XColorMap">
<int signed="true" width="32"/>
</item>
<item name="YColorMap">
<int signed="true" width="32"/>
</item>
<item name="ZColorMap">
<int signed="true" width="32"/>
</item>
<item name="IColorMap">
<int signed="true" width="32"/>
</item>
<item name="PointSize">
<float width="64"/>
</item>
</struct>
</item>
{
"class" : "View.PointCloudDecoration",
"data" : {
"XMax" : 100,
"YMax" : 100,
"ZMax" : 100,
"IMax" : 100,
"XMin" : -100,
"YMin" : -100,
"ZMin" : -100,
"IMin" : -100,
"XRangeSet" : true,
"YRangeSet" : true,
"ZRangeSet" : true,
"IRangeSet" : true,
"XColorMap" : 0,
"YColorMap" : 0,
"ZColorMap" : 0,
"IColorMap" : 0,
"PointSize" : 1
}
}
View.Present.Add
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Type">
<any_of>
<item>
<string value="HEIGHTMAP"/>
</item>
<item>
<string value="IMAGE"/>
</item>
<item>
<string value="PIXEL_REGION"/>
</item>
<item>
<string value="POINT_CLOUD"/>
</item>
<item>
<string value="SHAPE"/>
</item>
<item>
<string value="TEXT"/>
</item>
<item>
<string value="PROFILE"/>
</item>
<item>
<string value="POLAR_SCAN"/>
</item>
<item>
<string value="MESH"/>
</item>
<item>
<string value="CAMERAMODEL"/>
</item>
<item>
<string value="UNDEFINED"/>
</item>
</any_of>
</item>
<item name="Iconics">
<array>
<item>
<polymorphic/>
</item>
</array>
</item>
<item name="Decorations">
<array>
<item>
<polymorphic/>
</item>
</array>
</item>
<item name="CameraModel">
<polymorphic can_be_null="true">
<data_format_ref name="Image.Calibration.CameraModel"/>
</polymorphic>
</item>
<item name="Labels">
<array>
<item>
<string/>
</item>
</array>
</item>
<item name="IconicId">
<string/>
</item>
<item name="ParentId">
<string/>
</item>
</struct>
</item>
{
"class" : "View.Present.Add",
"data" : {
"Type" : "SHAPE",
"Iconics" : [ {
"class" : "Shape.Circle",
"data" : {
"cx" : 3,
"cy" : 3,
"radius" : 4
}
} ],
"Decorations" : [ {
"class" : "View.ShapeDecoration",
"data" : {
"LineColor" : {
"R" : 0,
"G" : 127,
"B" : 195,
"A" : 255
},
"FillColor" : {
"R" : 0,
"G" : 127,
"B" : 195,
"A" : 0
},
"LineWidth" : 1,
"PointSize" : 3,
"PointType" : "DOT"
}
} ],
"CameraModel" : null,
"Labels" : [ ],
"IconicId" : "_ID_ICONIC_2",
"ParentId" : "_ID_ICONIC_1"
}
}
View.Present.Clear
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct/>
</item>
{
"class" : "View.Present.Clear",
"data" : { }
}
View.Present.Editor
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Type">
<any_of>
<item>
<string value="INSTALL"/>
</item>
<item>
<string value="UNINSTALL"/>
</item>
</any_of>
</item>
<item name="IconicId">
<string/>
</item>
</struct>
</item>
{
"class" : "View.Present.Editor",
"data" : {
"Type" : "INSTALL",
"IconicId" : "_ID_ICONIC_1"
}
}
View.Present.Remove
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="IconicId">
<string/>
</item>
</struct>
</item>
{
"class" : "View.Present.Remove",
"data" : {
"IconicId" : "_ID_ICONIC_1"
}
}
View.Present.UpdateDecoration
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Decorations">
<array>
<item>
<polymorphic/>
</item>
</array>
</item>
<item name="IconicId">
<string/>
</item>
</struct>
</item>
{
"class" : "View.Present.UpdateDecoration",
"data" : {
"Decoration" : {
"class" : "View.ShapeDecoration",
"data" : {
"LineColor" : {
"R" : 0,
"G" : 127,
"B" : 195,
"A" : 255
},
"FillColor" : {
"R" : 0,
"G" : 127,
"B" : 195,
"A" : 0
},
"LineWidth" : 1,
"PointSize" : 3,
"PointType" : "DOT"
}
},
"IconicId" : "_ID_ICONIC_2"
}
}
View.Present.UpdateTransform
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Pose">
<data_format_ref name="Transform"/>
</item>
<item name="IconicId">
<string/>
</item>
</struct>
</item>
{
"class" : "View.Present.UpdateTransform",
"data" : {
"Transform" : {
"Type" : "TRANSLATION",
"Matrix" : [ [ 1, 0, 0, 5 ], [ 0, 1, 0, 6 ], [ 0, 0, 1, 7 ], [ 0, 0, 0, 1 ] ]
},
"IconicId" : "_ID_ICONIC_2"
}
}
View.ShapeDecoration
View.ShapeDecoration.Pixel.RGBA, View.ShapeDecoration.PointType
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="LineColor">
<data_format_ref name="View.ShapeDecoration.Pixel.RGBA"/>
</item>
<item name="FillColor">
<data_format_ref name="View.ShapeDecoration.Pixel.RGBA"/>
</item>
<item name="LineWidth">
<float width="32"/>
</item>
<item name="PointSize">
<float width="32"/>
</item>
<item name="PointType">
<data_format_ref name="View.ShapeDecoration.PointType"/>
</item>
</struct>
</item>
{
"class" : "View.ShapeDecoration",
"data" : {
"LineColor" : {
"R" : 0,
"G" : 127,
"B" : 195,
"A" : 255
},
"FillColor" : {
"R" : 0,
"G" : 127,
"B" : 195,
"A" : 0
},
"LineWidth" : 1,
"PointSize" : 3,
"PointType" : "DOT"
}
}
View.ShapeDecoration.Pixel.RGBA
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="R" desc="Red component">
<int signed="false" width="8"/>
</item>
<item name="G" desc="Green component">
<int signed="false" width="8"/>
</item>
<item name="B" desc="Blue component">
<int signed="false" width="8"/>
</item>
<item name="A" desc="Alpha component">
<int signed="false" width="8"/>
</item>
</struct>
</item>
View.ShapeDecoration.PointType
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<any_of>
<item>
<string value="DOT"/>
</item>
<item>
<string value="CROSS"/>
</item>
</any_of>
</item>
View.TextDecoration
Point3D, Point3D_32, View.TextDecoration.Bounds, View.TextDecoration.FontFamily, View.TextDecoration.FontWeight, View.TextDecoration.HorizontalAlignment, View.TextDecoration.RGBA, View.TextDecoration.VerticalAlignment
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="FontSize">
<int signed="true" width="64"/>
</item>
<item name="Position">
<data_format_ref name="Point3D_32"/>
</item>
<item name="HorizontalAlignment">
<data_format_ref name="View.TextDecoration.HorizontalAlignment"/>
</item>
<item name="VerticalAlignment">
<data_format_ref name="View.TextDecoration.VerticalAlignment"/>
</item>
<item name="FontWeight">
<data_format_ref name="View.TextDecoration.FontWeight"/>
</item>
<item name="FontFamily">
<data_format_ref name="View.TextDecoration.FontFamily"/>
</item>
<item name="Rotation">
<float width="64"/>
</item>
<item name="RotationAxis">
<data_format_ref name="Point3D"/>
</item>
<item name="BillboardActive">
<bool/>
</item>
<item name="Bounds">
<data_format_ref name="View.TextDecoration.Bounds"/>
</item>
<item name="LineSpacing">
<float width="64"/>
</item>
<item name="Color">
<data_format_ref name="View.TextDecoration.RGBA"/>
</item>
</struct>
</item>
{
"class" : "View.TextDecoration",
"data" : {
"FontSize" : 10,
"Position" : {
"x" : 0,
"y" : 0,
"z" : 0
},
"HorizontalAlignment" : "LEFT",
"VerticalAlignment" : "BOTTOM",
"FontWeight" : "NORMAL",
"FontFamily" : "SANSSERIF",
"Rotation" : 0,
"RotationAxis" : {
"x" : 0,
"y" : 0,
"z" : 0
},
"BillboardActive" : true,
"Bounds" : {
"Width" : 42,
"Height" : 46
},
"LineSpacing" : 1.1,
"Color" : {
"R" : 0,
"G" : 127,
"B" : 195,
"A" : 255
}
}
}
View.TextDecoration.Bounds
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="Width" desc="Width component">
<int signed="false" width="32"/>
</item>
<item name="Height" desc="Height component">
<int signed="false" width="32"/>
</item>
</struct>
</item>
View.TextDecoration.FontFamily
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<any_of>
<item>
<string value="SANSSERIF"/>
</item>
<item>
<string value="MONOSPACE"/>
</item>
<item>
<string value="SERIF"/>
</item>
</any_of>
</item>
View.TextDecoration.FontWeight
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<any_of>
<item>
<string value="NORMAL"/>
</item>
<item>
<string value="BOLD"/>
</item>
</any_of>
</item>
View.TextDecoration.HorizontalAlignment
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<any_of>
<item>
<string value="LEFT"/>
</item>
<item>
<string value="CENTERH"/>
</item>
<item>
<string value="RIGHT"/>
</item>
<item>
<string value="JUSTIFY"/>
</item>
</any_of>
</item>
View.TextDecoration.RGBA
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<struct>
<item name="R" desc="Red component">
<int signed="false" width="8"/>
</item>
<item name="G" desc="Green component">
<int signed="false" width="8"/>
</item>
<item name="B" desc="Blue component">
<int signed="false" width="8"/>
</item>
<item name="A" desc="Alpha component">
<int signed="false" width="8"/>
</item>
</struct>
</item>
View.TextDecoration.VerticalAlignment
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<item>
<any_of>
<item>
<string value="BOTTOM"/>
</item>
<item>
<string value="CENTERV"/>
</item>
<item>
<string value="TOP"/>
</item>
</any_of>
</item>